Merge pull request #95 from 0xFelix/improved-docs

Provide links for docsite and improve docs by adding markup

docs/docsite/links.yml

@@ -1,45 +1,13 @@
 ---
-# This will make sure that plugin and module documentation gets Edit on GitHub links
-# that allow users to directly create a PR for this plugin or module in GitHub's UI.
-# Remove this section if the collection repository is not on GitHub, or if you do not want this
-# functionality for your collection.
 edit_on_github:
-  repository: ansible-collections/community.REPO_NAME
+  repository: kubevirt/kubevirt.core
   branch: main
-  # If your collection root (the directory containing galaxy.yml) does not coincide with your
-  # repository's root, you have to specify the path to the collection root here. For example,
-  # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME
-  # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'.
-  path_prefix: ''
-
-# Here you can add arbitrary extra links. Please keep the number of links down to a
-# minimum! Also please keep the description short, since this will be the text put on
-# a button.
-#
-# Also note that some links are automatically added from information in galaxy.yml.
-# The following are automatically added:
-#   1. A link to the issue tracker (if `issues` is specified);
-#   2. A link to the homepage (if `homepage` is specified and does not equal the
-#      `documentation` or `repository` link);
-#   3. A link to the collection's repository (if `repository` is specified).
 
 extra_links:
   - description: Report an issue
-    url: https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose
+    url: https://github.com/kubevirt/kubevirt.core/issues/new/choose
 
-# Specify communication channels for your collection. We suggest to not specify more
-# than one place for communication per communication tool to avoid confusion.
 communication:
-  matrix_rooms:
-    - topic: General usage and support questions
-      room: '#users:ansible.im'
-  irc_channels:
-    - topic: General usage and support questions
-      network: Libera
-      channel: '#ansible'
   mailing_lists:
-    - topic: Ansible Project List
-      url: https://groups.google.com/g/ansible-project
-      # You can also add a `subscribe` field with an URI that allows to subscribe
-      # to the mailing list. For lists on https://groups.google.com/ a subscribe link is
-      # automatically generated.
+    - topic: kubevirt-dev List
+      url: https://groups.google.com/g/kubevirt-dev

plugins/inventory/kubevirt.py

@@ -16,23 +16,23 @@
 - "KubeVirt.io Project (!UNKNOWN)"
 
 description:
-- Fetch running VirtualMachineInstances for one or more namespaces with an optional label selector.
-- Groups by namespace, namespace_vmis and labels.
-- Uses the kubectl connection plugin to access the Kubernetes cluster.
-- Uses *.kubevirt.(yml|yaml) YAML configuration file to set parameter values.
+- Fetch running C(VirtualMachineInstances) for one or more namespaces with an optional label selector.
+- Groups by cluster name, namespace and labels.
+- Uses the M(kubernetes.core.kubectl) connection plugin to access the Kubernetes cluster.
+- Uses V(*.kubevirt.[yml|yaml]) YAML configuration file to set parameter values.
 
 extends_documentation_fragment:
 - inventory_cache
 - constructed
 
 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 @@
         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.
-        - Services are only used if no network_name was provided.
+        - Enable the use of C(Services) to establish an SSH connection to the C(VirtualMachine).
+        - 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
-          kubesecondarydns or services of type NodePort if append_base_domain is set.
+        - Override the base domain used to construct host names of C(VirtualMachines). Used in case of
+          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 @@
     default: kubevirt.io/v1
   name:
     description:
-    - Specify the name of the VirtualMachine.
-    - This option is ignored when I(state) is not set to C(present).
-    - mutually exclusive with C(generate_name).
+    - Specify the name of the C(VirtualMachine).
+    - This option is ignored when O(state=present) is not set.
+    - 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).
-    - mutually exclusive with C(name).
+    - Only used when O(state=present).
+    - 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.
-    - Only used when I(state=present).
+    - Specify annotations to set on the C(VirtualMachine).
+    - 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.
-    - Only used when I(state=present).
+    - Specify the C(Instancetype) matcher of the C(VirtualMachine).
+    - Only used when O(state=present).
     type: dict
   preference:
     description:
-    - Specify the preference matcher of the VirtualMachine.
-    - Only used when I(state=present).
+    - Specify the C(Preference) matcher of the C(VirtualMachine).
+    - Only used when O(state=present).
     type: dict
   data_volume_templates:
     description:
-    - Specify the DataVolume templates of the VirtualMachine.
-    - 'See: https://kubevirt.io/api-reference/main/definitions.html#_v1_datavolumetemplatespec'
+    - Specify the C(DataVolume) templates of the C(VirtualMachine).
+    - 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.
-    - 'See: https://kubevirt.io/api-reference/main/definitions.html#_v1_virtualmachineinstancespec'
+    - Specify the template spec of the C(VirtualMachine).
+    - 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.
-    - Ignored if C(wait) is not set.
+    - How long in seconds to wait for the resource to end up in the ready state.
+    - Ignored if O(wait) is not set.
     default: 120
     type: int
 
@@ -205,12 +205,12 @@
   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
-      returned: when C(wait) is true
+      description: Elapsed time of the task in seconds.
+      returned: When O(wait=true).
       type: int
       sample: 48
     method: