From 0fd9f625ee511fd44a79c3b1707cb864f15d4011 Mon Sep 17 00:00:00 2001 From: Felix Matouschek Date: Thu, 2 May 2024 14:38:14 +0200 Subject: [PATCH 1/2] docs: Provide links for docsite Fill in the links.yml template and provide correct links and communication channels for the collection. Signed-off-by: Felix Matouschek --- docs/docsite/links.yml | 40 ++++------------------------------------ 1 file changed, 4 insertions(+), 36 deletions(-) diff --git a/docs/docsite/links.yml b/docs/docsite/links.yml index d760eb5..abfddfb 100644 --- a/docs/docsite/links.yml +++ b/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 From 4851e5d20d4a41f041636fdd39e4eb2d2e418bb7 Mon Sep 17 00:00:00 2001 From: Felix Matouschek Date: Tue, 7 May 2024 14:51:13 +0200 Subject: [PATCH 2/2] docs: Improve docs by adding markup Improve the generated documentations by adding Ansible documentation markup where appropriate. Signed-off-by: Felix Matouschek --- plugins/inventory/kubevirt.py | 52 ++++++++++++++--------------- plugins/modules/kubevirt_vm.py | 52 ++++++++++++++--------------- plugins/modules/kubevirt_vm_info.py | 38 ++++++++++----------- 3 files changed, 71 insertions(+), 71 deletions(-) diff --git a/plugins/inventory/kubevirt.py b/plugins/inventory/kubevirt.py index e30cd5f..0889d02 100644 --- a/plugins/inventory/kubevirt.py +++ b/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. -- 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 @@ -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. - - 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: diff --git a/plugins/modules/kubevirt_vm.py b/plugins/modules/kubevirt_vm.py index a5e39bb..7f742ef 100644 --- a/plugins/modules/kubevirt_vm.py +++ b/plugins/modules/kubevirt_vm.py @@ -35,72 +35,72 @@ options: 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 @@ 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 - returned: when C(wait) is true + description: Elapsed time of the task in seconds. + returned: When O(wait=true). type: int sample: 48 method: diff --git a/plugins/modules/kubevirt_vm_info.py b/plugins/modules/kubevirt_vm_info.py index 3bbffb7..422849b 100644 --- a/plugins/modules/kubevirt_vm_info.py +++ b/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. - - Pass options to find VirtualMachines as module arguments. + - Use the Kubernetes Python client to perform read operations on KubeVirt C(VirtualMachines). + - 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. - - By default this is waiting for the VirtualMachine to be up and running. - - Modify this behavior by setting C(running). + - Whether to wait for the C(VirtualMachine) to end up in the ready state. + - By default this is waiting for the C(VirtualMachine) to be up and 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. - - 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 @@ -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 """