docs: Improve docs by adding markup

Improve the generated documentations by adding Ansible documentation markup
where appropriate.

Signed-off-by: Felix Matouschek <fmatouschek@redhat.com>

plugins/inventory/kubevirt.py

@@ -16,10 +16,10 @@ author:
 - "KubeVirt.io Project (!UNKNOWN)"
 
 description:
-- Fetch running VirtualMachineInstances for one or more namespaces with an optional label selector.
+- Fetch running C(VirtualMachineInstances) for one or more namespaces with an optional label selector.
-- Groups by namespace, namespace_vmis and labels.
+- Groups by cluster name, namespace and labels.
-- Uses the kubectl connection plugin to access the Kubernetes cluster.
+- Uses the M(kubernetes.core.kubectl) connection plugin to access the Kubernetes cluster.
-- Uses *.kubevirt.(yml|yaml) YAML configuration file to set parameter values.
+- Uses V(*.kubevirt.[yml|yaml]) YAML configuration file to set parameter values.
 
 extends_documentation_fragment:
 - inventory_cache
@@ -27,12 +27,12 @@ extends_documentation_fragment:
 
 options:
   plugin:
-    description: Token that ensures this is a source file for the "kubevirt" plugin.
+    description: Token that ensures this is a source file for the P(kubevirt.core.kubevirt#inventory) plugin.
     required: True
     choices: ["kubevirt", "kubevirt.core.kubevirt"]
   host_format:
     description:
-    - 'Specify the format of the host in the inventory group. Available specifiers: name, namespace, uid.'
+    - 'Specify the format of the host in the inventory group. Available specifiers: V(name), V(namespace) and V(uid).'
     default: "{namespace}-{name}"
   connections:
     description:
@@ -50,83 +50,83 @@ options:
         description:
         - Path to an existing Kubernetes config file. If not provided, and no other connection
           options are provided, the Kubernetes client will attempt to load the default
-          configuration file from I(~/.kube/config). Can also be specified via K8S_AUTH_KUBECONFIG
+          configuration file from I(~/.kube/config). Can also be specified via E(K8S_AUTH_KUBECONFIG)
           environment variable.
       context:
         description:
-        - The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment
+        - The name of a context found in the config file. Can also be specified via E(K8S_AUTH_CONTEXT) environment
           variable.
       host:
         description:
-        - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+        - Provide a URL for accessing the API. Can also be specified via E(K8S_AUTH_HOST) environment variable.
       api_key:
         description:
-        - Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment
+        - Token used to authenticate with the API. Can also be specified via E(K8S_AUTH_API_KEY) environment
           variable.
       username:
         description:
-        - Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME
+        - Provide a username for authenticating with the API. Can also be specified via E(K8S_AUTH_USERNAME)
           environment variable.
       password:
         description:
-        - Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD
+        - Provide a password for authenticating with the API. Can also be specified via E(K8S_AUTH_PASSWORD)
           environment variable.
       client_cert:
         description:
-        - Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE
+        - Path to a certificate used to authenticate with the API. Can also be specified via E(K8S_AUTH_CERT_FILE)
           environment variable.
         aliases: [ cert_file ]
       client_key:
         description:
-        - Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE
+        - Path to a key file used to authenticate with the API. Can also be specified via E(K8S_AUTH_KEY_FILE)
           environment variable.
         aliases: [ key_file ]
       ca_cert:
         description:
         - Path to a CA certificate used to authenticate with the API. Can also be specified via
-          K8S_AUTH_SSL_CA_CERT environment variable.
+          E(K8S_AUTH_SSL_CA_CERT) environment variable.
         aliases: [ ssl_ca_cert ]
       validate_certs:
         description:
         - Whether or not to verify the API server's SSL certificates. Can also be specified via
-          K8S_AUTH_VERIFY_SSL environment variable.
+          E(K8S_AUTH_VERIFY_SSL) environment variable.
         type: bool
         aliases: [ verify_ssl ]
       namespaces:
         description:
-        - List of namespaces. If not specified, will fetch all VirtualMachineInstances for all namespaces
+        - List of namespaces. If not specified, will fetch all C(VirtualMachineInstances) for all namespaces
           the user is authorized to access.
       label_selector:
         description:
-        - Define a label selector to select a subset of the fetched VirtualMachineInstances.
+        - Define a label selector to select a subset of the fetched C(VirtualMachineInstances).
       network_name:
         description:
-        - In case multiple networks are attached to a VirtualMachineInstance, define which interface should
+        - In case multiple networks are attached to a C(VirtualMachineInstance), define which interface should
           be returned as primary IP address.
         aliases: [ interface_name ]
       kube_secondary_dns:
         description:
-        - Enable kubesecondarydns derived host names when using a secondary network interface.
+        - Enable C(kubesecondarydns) derived host names when using a secondary network interface.
         type: bool
         default: False
       use_service:
         description:
-        - Enable the use of services to establish an SSH connection to the VirtualMachine.
+        - Enable the use of C(Services) to establish an SSH connection to the C(VirtualMachine).
-        - Services are only used if no network_name was provided.
+        - Services are only used if no O(connections.network_name) was provided.
         type: bool
         default: True
       create_groups:
         description:
-        - Enable the creation of groups from labels on VirtualMachines.
+        - Enable the creation of groups from labels on C(VirtualMachines).
         type: bool
         default: False
       base_domain:
         description:
-        - Override the base domain used to construct host names of VirtualMachines. Used in case of
+        - Override the base domain used to construct host names of C(VirtualMachines). Used in case of
-          kubesecondarydns or services of type NodePort if append_base_domain is set.
+          C(kubesecondarydns) or C(Services) of type C(NodePort) if O(connections.append_base_domain) is set.
       append_base_domain:
         description:
-        - Append the base domain of the cluster to host names constructed from SSH services of type NodePort.
+        - Append the base domain of the cluster to host names constructed from SSH C(Services) of type C(NodePort).
         type: bool
         default: False
       api_version:

plugins/modules/kubevirt_vm.py

@@ -35,72 +35,72 @@ options:
     default: kubevirt.io/v1
   name:
     description:
-    - Specify the name of the VirtualMachine.
+    - Specify the name of the C(VirtualMachine).
-    - This option is ignored when I(state) is not set to C(present).
+    - This option is ignored when O(state=present) is not set.
-    - mutually exclusive with C(generate_name).
+    - Mutually exclusive with O(generate_name).
     type: str
   generate_name:
     description:
-    - Specify the basis of the VirtualMachine name and random characters will be added automatically on server to
+    - Specify the basis of the C(VirtualMachine) name and random characters will be added automatically on the cluster to
       generate a unique name.
-    - Only used when I(state=present).
+    - Only used when O(state=present).
-    - mutually exclusive with C(name).
+    - Mutually exclusive with O(name).
     type: str
   namespace:
     description:
-    - Specify the namespace of the VirtualMachine.
+    - Specify the namespace of the C(VirtualMachine).
     type: str
     required: yes
   annotations:
     description:
-    - Specify annotations to set on the VirtualMachine.
+    - Specify annotations to set on the C(VirtualMachine).
-    - Only used when I(state=present).
+    - Only used when O(state=present).
     type: dict
   labels:
     description:
-    - Specify labels to set on the VirtualMachine.
+    - Specify labels to set on the C(VirtualMachine).
     type: dict
   running:
     description:
-    - Specify whether the VirtualMachine should be running.
+    - Specify whether the C(VirtualMachine) should be running or not.
     type: bool
     default: yes
   instancetype:
     description:
-    - Specify the instancetype matcher of the VirtualMachine.
+    - Specify the C(Instancetype) matcher of the C(VirtualMachine).
-    - Only used when I(state=present).
+    - Only used when O(state=present).
     type: dict
   preference:
     description:
-    - Specify the preference matcher of the VirtualMachine.
+    - Specify the C(Preference) matcher of the C(VirtualMachine).
-    - Only used when I(state=present).
+    - Only used when O(state=present).
     type: dict
   data_volume_templates:
     description:
-    - Specify the DataVolume templates of the VirtualMachine.
+    - Specify the C(DataVolume) templates of the C(VirtualMachine).
-    - 'See: https://kubevirt.io/api-reference/main/definitions.html#_v1_datavolumetemplatespec'
+    - See U(https://kubevirt.io/api-reference/main/definitions.html#_v1_datavolumetemplatespec)
     type: list
     elements: 'dict'
   spec:
     description:
-    - Specify the template spec of the VirtualMachine.
+    - Specify the template spec of the C(VirtualMachine).
-    - 'See: https://kubevirt.io/api-reference/main/definitions.html#_v1_virtualmachineinstancespec'
+    - See U(https://kubevirt.io/api-reference/main/definitions.html#_v1_virtualmachineinstancespec)
     type: dict
   wait:
     description:
-    - Whether to wait for the VirtualMachine to end up in the ready state.
+    - Whether to wait for the C(VirtualMachine) to end up in the ready state.
     type: bool
     default: no
   wait_sleep:
     description:
     - Number of seconds to sleep between checks.
-    - Ignored if C(wait) is not set.
+    - Ignored if O(wait) is not set.
     default: 5
     type: int
   wait_timeout:
     description:
-    - How long in seconds to wait for the resource to end up in the desired state.
+    - How long in seconds to wait for the resource to end up in the ready state.
-    - Ignored if C(wait) is not set.
+    - Ignored if O(wait) is not set.
     default: 120
     type: int
 
@@ -205,12 +205,12 @@ result:
   returned: success
   contains:
     changed:
-      description: Whether the VirtualMachine was changed
+      description: Whether the C(VirtualMachine) was changed or not.
       type: bool
       sample: True
     duration:
-      description: elapsed time of task in seconds
+      description: Elapsed time of the task in seconds.
-      returned: when C(wait) is true
+      returned: When O(wait=true).
       type: int
       sample: 48
     method:

plugins/modules/kubevirt_vm_info.py

@@ -17,8 +17,8 @@ author:
 - "KubeVirt.io Project (!UNKNOWN)"
 
 description:
-  - Use the Kubernetes Python client to perform read operations on KubeVirt VirtualMachines.
+  - Use the Kubernetes Python client to perform read operations on KubeVirt C(VirtualMachines).
-  - Pass options to find VirtualMachines as module arguments.
+  - Pass options to find C(VirtualMachines) as module arguments.
   - Authenticate using either a config file, certificates, password or token.
   - Supports check mode.
 
@@ -30,45 +30,45 @@ options:
     default: kubevirt.io/v1
   name:
     description:
-    - Specify the name of the VirtualMachine.
+    - Specify the name of the C(VirtualMachine).
     type: str
   namespace:
     description:
-    - Specify the namespace of VirtualMachines.
+    - Specify the namespace of C(VirtualMachines).
     type: str
   label_selectors:
-    description: List of label selectors to use to filter results
+    description: List of label selectors to use to filter results.
     type: list
     elements: str
     default: []
   field_selectors:
-    description: List of field selectors to use to filter results
+    description: List of field selectors to use to filter results.
     type: list
     elements: str
     default: []
   running:
     description:
-    - Specify whether the VirtualMachine should be running.
+    - Specify whether the C(VirtualMachine) should be running or not.
     - This affects the ready condition to wait for.
-    - This requires C(wait) and is only used when I(wait=yes).
+    - This requires O(wait=yes).
     type: bool
     version_added: 1.4.0
   wait:
     description:
-    - Whether to wait for the VirtualMachine to end up in the ready state.
+    - Whether to wait for the C(VirtualMachine) to end up in the ready state.
-    - By default this is waiting for the VirtualMachine to be up and running.
+    - By default this is waiting for the C(VirtualMachine) to be up and running.
-    - Modify this behavior by setting C(running).
+    - Modify this behavior by setting O(running).
     type: bool
   wait_sleep:
     description:
     - Number of seconds to sleep between checks.
-    - Ignored if C(wait) is not set.
+    - Ignored if O(wait) is not set.
     default: 5
     type: int
   wait_timeout:
     description:
-    - How long in seconds to wait for the resource to end up in the desired state.
+    - How long in seconds to wait for the resource to end up in the ready state.
-    - Ignored if C(wait) is not set.
+    - Ignored if O(wait) is not set.
     default: 120
     type: int
 
@@ -119,12 +119,12 @@ EXAMPLES = """
 RETURN = """
 api_found:
   description:
-  - Whether the specified api_version and VirtualMachine kind were successfully mapped to an existing API on the targeted cluster.
+  - Whether the specified O(api_version) and C(VirtualMachine) C(Kind) were successfully mapped to an existing API on the target cluster.
   returned: always
   type: bool
 resources:
   description:
-  - The VirtualMachine(s) that exist(s)
+  - The C(VirtualMachines) that exist.
   returned: success
   type: complex
   contains:
@@ -133,7 +133,7 @@ resources:
       returned: success
       type: str
     kind:
-      description: Represents the REST resource this object represents.
+      description: Represents the C(REST) resource this object represents.
       returned: success
       type: str
     metadata:
@@ -141,11 +141,11 @@ resources:
       returned: success
       type: dict
     spec:
-      description: Specific attributes of the VirtualMachine. Can vary based on the I(api_version).
+      description: Specific attributes of the C(VirtualMachine). Can vary based on the O(api_version).
       returned: success
       type: dict
     status:
-      description: Current status details for the VirtualMachine.
+      description: Current status details for the C(VirtualMachine).
       returned: success
       type: dict
 """