From c184a25155d0bb0730cf65b327d6d70bc3edd9fd Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 1 Oct 2024 15:57:12 +0200 Subject: [PATCH] stable-4.x: Fix documentation (#2193) SUMMARY Fix documentation. ISSUE TYPE Docs Pull Request COMPONENT NAME vcenter_standard_key_provider vmware_dvswitch_nioc vmware_guest vmware_guest_controller vmware_guest_disk vmware_guest_serial_port vmware_tools ADDITIONAL INFORMATION Backport of #2192 --- .github/workflows/extra-docs-linting.yml | 2 +- .../fragments/2192-fix-documentation.yml | 15 ++++++++ plugins/connection/vmware_tools.py | 2 +- .../modules/vcenter_standard_key_provider.py | 8 ++--- plugins/modules/vmware_dvswitch_nioc.py | 2 +- plugins/modules/vmware_guest.py | 28 +++++++-------- plugins/modules/vmware_guest_controller.py | 4 +-- plugins/modules/vmware_guest_disk.py | 36 +++++++++---------- plugins/modules/vmware_guest_serial_port.py | 28 +++++++-------- 9 files changed, 70 insertions(+), 55 deletions(-) create mode 100644 changelogs/fragments/2192-fix-documentation.yml diff --git a/.github/workflows/extra-docs-linting.yml b/.github/workflows/extra-docs-linting.yml index 91e3524fa4..e16e080369 100644 --- a/.github/workflows/extra-docs-linting.yml +++ b/.github/workflows/extra-docs-linting.yml @@ -32,4 +32,4 @@ jobs: run: pip install antsibull-docs --disable-pip-version-check - name: Run collection docs linter - run: antsibull-docs lint-collection-docs . + run: antsibull-docs lint-collection-docs . --plugin-docs --skip-rstcheck diff --git a/changelogs/fragments/2192-fix-documentation.yml b/changelogs/fragments/2192-fix-documentation.yml new file mode 100644 index 0000000000..0151e252ba --- /dev/null +++ b/changelogs/fragments/2192-fix-documentation.yml @@ -0,0 +1,15 @@ +bugfixes: + - vcenter_standard_key_provider - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_dvswitch_nioc - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_guest - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_guest_controller - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_guest_disk - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_guest_serial_port - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). + - vmware_tools - Fix documentation + (https://github.com/ansible-collections/community.vmware/pull/2192). diff --git a/plugins/connection/vmware_tools.py b/plugins/connection/vmware_tools.py index a542a64a1c..1c7328880a 100644 --- a/plugins/connection/vmware_tools.py +++ b/plugins/connection/vmware_tools.py @@ -88,7 +88,7 @@ description: - Mutually exclusive with O(vm_path) - VM UUID to the connection. - - UUID of the virtual machine from property config.uuid of P(community.vmware.vmware_vm_inventory#lookup) plugin + - UUID of the virtual machine from property config.uuid of P(community.vmware.vmware_vm_inventory#inventory) plugin vars: - name: ansible_vmware_guest_uuid required: false diff --git a/plugins/modules/vcenter_standard_key_provider.py b/plugins/modules/vcenter_standard_key_provider.py index 8ce8f48c6b..bf00966201 100644 --- a/plugins/modules/vcenter_standard_key_provider.py +++ b/plugins/modules/vcenter_standard_key_provider.py @@ -43,9 +43,9 @@ kms_info: description: - The information of an external key server (KMS). - - O(kms_info.kms_name), O(kms_info.kms_ip) are required when adding a Standard Key Provider. - - If O(kms_info.kms_port) is not specified, the default port 5696 will be used. - - O(kms_info.kms_ip), O(kms_info.kms_port) can be reconfigured for an existing KMS with name O(kms_info.kms_name). + - O(kms_info[].kms_name), O(kms_info[].kms_ip) are required when adding a Standard Key Provider. + - If O(kms_info[].kms_port) is not specified, the default port 5696 will be used. + - O(kms_info[].kms_ip), O(kms_info[].kms_port) can be reconfigured for an existing KMS with name O(kms_info[].kms_name). type: list default: [] elements: dict @@ -60,7 +60,7 @@ description: Port of the external KMS. type: int remove_kms: - description: Remove the configured KMS with name O(kms_info.kms_name) from the KMIP cluster. + description: Remove the configured KMS with name O(kms_info[].kms_name) from the KMIP cluster. type: bool proxy_server: description: Address of the proxy server to connect to KMS. diff --git a/plugins/modules/vmware_dvswitch_nioc.py b/plugins/modules/vmware_dvswitch_nioc.py index 6f3d182f76..f526c2d8b3 100644 --- a/plugins/modules/vmware_dvswitch_nioc.py +++ b/plugins/modules/vmware_dvswitch_nioc.py @@ -77,7 +77,7 @@ shares: description: - The number of shares allocated. - - Ignored unless O(resources.shares_level=custom). + - Ignored unless O(resources[].shares_level=custom). type: int required: false type: list diff --git a/plugins/modules/vmware_guest.py b/plugins/modules/vmware_guest.py index eb3923038a..9bf8256d5b 100644 --- a/plugins/modules/vmware_guest.py +++ b/plugins/modules/vmware_guest.py @@ -262,7 +262,7 @@ - A list of disks to add. - Shrinking disks is not supported. - Removing existing disks of the virtual machine is not supported. - - 'Attributes O(disk.controller_type), O(disk.controller_number), O(disk.unit_number) are used to configure multiple types of disk + - 'Attributes O(disk[].controller_type), O(disk[].controller_number), O(disk[].unit_number) are used to configure multiple types of disk controllers and disks for creating or reconfiguring virtual machine.' type: list default: [] @@ -295,7 +295,7 @@ type: str description: - The name of datastore which will be used for the disk. - - If O(disk.autoselect_datastore) is set to True, will select the less used datastore whose name contains this "disk.datastore" string. + - If O(disk[].autoselect_datastore) is set to True, will select the less used datastore whose name contains this "disk.datastore" string. filename: type: str description: @@ -306,7 +306,7 @@ type: bool description: - Select the less used datastore. - - O(disk.datastore) and O(disk.autoselect_datastore) will not be used if O(datastore) is specified outside this O(disk) configuration. + - O(disk[].datastore) and O(disk[].autoselect_datastore) will not be used if O(datastore) is specified outside this O(disk[]) configuration. disk_mode: type: str choices: ['persistent', 'independent_persistent', 'independent_nonpersistent'] @@ -322,8 +322,8 @@ description: - Type of disk controller. Set this type on not supported ESXi or VM hardware version will lead to failure in deployment. - - When set to V(sata), please make sure O(disk.unit_number) is correct and not used by SATA CDROMs. - - If set to V(sata) type, please make sure O(disk.controller_number) and O(disk.unit_number) are set correctly when O(cdrom=sata). + - When set to V(sata), please make sure O(disk[].unit_number) is correct and not used by SATA CDROMs. + - If set to V(sata) type, please make sure O(disk[].controller_number) and O(disk[].unit_number) are set correctly when O(cdrom=sata). controller_number: type: int choices: [0, 1, 2, 3] @@ -337,9 +337,9 @@ - Valid value range from 0 to 15 for SCSI controller, except 7. - Valid value range from 0 to 14 for NVME controller. - Valid value range from 0 to 29 for SATA controller. - - O(disk.controller_type), O(disk.controller_number) and O(disk.unit_number) are required when creating or reconfiguring VMs + - O(disk[].controller_type), O(disk[].controller_number) and O(disk[].unit_number) are required when creating or reconfiguring VMs with multiple types of disk controllers and disks. - - When creating new VM, the first configured disk in the O(disk) list will be "Hard Disk 1". + - When creating new VM, the first configured disk in the O(disk[]) list will be "Hard Disk 1". nvdimm: description: - Add or remove a virtual NVDIMM device to the virtual machine. @@ -389,20 +389,20 @@ controller_type: type: str description: - - When set to V(sata), please make sure O(cdrom.unit_number) is correct and not used by SATA disks. + - When set to V(sata), please make sure O(cdrom[].unit_number) is correct and not used by SATA disks. choices: [ 'ide', 'sata' ] default: ide controller_number: type: int description: - - For O(cdrom.controller_type=ide), valid value is 0 or 1. - - For O(cdrom.controller_type=sata), valid value is 0 to 3. + - For O(cdrom[].controller_type=ide), valid value is 0 or 1. + - For O(cdrom[].controller_type=sata), valid value is 0 to 3. unit_number: type: int description: - - For O(cdrom.controller_type=ide), valid value is 0 or 1. - - For O(cdrom.controller_type=sata), valid value is 0 to 29. - - O(cdrom.controller_number) and O(cdrom.unit_number) are mandatory attributes. + - For O(cdrom[].controller_type=ide), valid value is 0 or 1. + - For O(cdrom[].controller_type=sata), valid value is 0 to 29. + - O(cdrom[].controller_number) and O(cdrom[].unit_number) are mandatory attributes. state: type: str description: @@ -788,7 +788,7 @@ datastore: description: - Specify datastore or datastore cluster to provision virtual machine. - - This parameter takes precedence over O(disk.datastore) parameter. + - This parameter takes precedence over O(disk[].datastore) parameter. - This parameter can be used to override datastore or datastore cluster setting of the virtual machine when deployed from the template. - Please see example for more usage. diff --git a/plugins/modules/vmware_guest_controller.py b/plugins/modules/vmware_guest_controller.py index 7084d9a210..e9c24bef98 100644 --- a/plugins/modules/vmware_guest_controller.py +++ b/plugins/modules/vmware_guest_controller.py @@ -69,8 +69,8 @@ suboptions: controller_number: description: - - Disk controller bus number. When O(controllers.state=absent), this parameter is required. - - When O(controllers.type=usb2) or O(controllers.type=usb3), this parameter is not required. + - Disk controller bus number. When O(controllers[].state=absent), this parameter is required. + - When O(controllers[].type=usb2) or O(controllers[].type=usb3), this parameter is not required. type: int choices: - 0 diff --git a/plugins/modules/vmware_guest_disk.py b/plugins/modules/vmware_guest_disk.py index 8a4fee90d4..960fe89175 100644 --- a/plugins/modules/vmware_guest_disk.py +++ b/plugins/modules/vmware_guest_disk.py @@ -97,13 +97,13 @@ - If set to V(independent_persistent) mode, same as persistent, but not affected by snapshots. - If set to V('independent_nonpersistent) mode, changes to virtual disk are made to a redo log and discarded at power off, but not affected by snapshots. - - Not applicable when disk O(disk.type=vpmemdisk). + - Not applicable when disk O(disk[].type=vpmemdisk). type: str choices: ['persistent', 'independent_persistent', 'independent_nonpersistent'] rdm_path: description: - - Path of LUN for Raw Device Mapping required for O(disk.type=rdm). - - Only valid if O(disk.type=rdm). + - Path of LUN for Raw Device Mapping required for O(disk[].type=rdm). + - Only valid if O(disk[].type=rdm). type: str cluster_disk: description: @@ -113,25 +113,25 @@ type: bool default: false compatibility_mode: - description: Compatibility mode for raw devices. Required when O(disk.type=rdm). + description: Compatibility mode for raw devices. Required when O(disk[].type=rdm). type: str choices: ['physicalMode','virtualMode'] sharing: description: - The sharing mode of the virtual disk. - Setting sharing means that multiple virtual machines can write to the virtual disk. - - Sharing can only be set if O(disk.type=eagerzeroedthick) or O(disk.type=rdm). + - Sharing can only be set if O(disk[].type=eagerzeroedthick) or O(disk[].type=rdm). type: bool default: false datastore: description: - Name of datastore or datastore cluster to be used for the disk. - - Not applicable when disk O(disk.type=vpmemdisk). + - Not applicable when disk O(disk[].type=vpmemdisk). type: str autoselect_datastore: description: - - Select the less used datastore. Specify only if O(disk.datastore) is not specified. - - Not applicable when disk O(disk.type=vpmemdisk). + - Select the less used datastore. Specify only if O(disk[].datastore) is not specified. + - Not applicable when disk O(disk[].type=vpmemdisk). type: bool scsi_controller: description: @@ -158,18 +158,18 @@ scsi_type: description: - Type of SCSI controller. This value is required only for the first occurrence of SCSI Controller. - - This value is ignored, if SCSI Controller is already present or O(disk.state=absent). + - This value is ignored, if SCSI Controller is already present or O(disk[].state=absent). type: str choices: ['buslogic', 'lsilogic', 'lsilogicsas', 'paravirtual'] destroy: - description: If O(disk.state=absent), make sure the disk file is deleted from the datastore. + description: If O(disk[].state=absent), make sure the disk file is deleted from the datastore. type: bool default: true filename: description: - Existing disk image to be used. Filename must already exist on the datastore. - Specify filename string in C([datastore_name] path/to/file.vmdk) format. - - Not applicable when disk O(disk.type=vpmemdisk). + - Not applicable when disk O(disk[].type=vpmemdisk). type: str state: description: @@ -183,19 +183,19 @@ controller_type: description: - This parameter is added for managing disks attaching other types of controllers, e.g., SATA or NVMe. - - If either O(disk.controller_type) or O(disk.scsi_type) is not specified, then use V(paravirtual) type. + - If either O(disk[].controller_type) or O(disk[].scsi_type) is not specified, then use V(paravirtual) type. type: str choices: ['buslogic', 'lsilogic', 'lsilogicsas', 'paravirtual', 'sata', 'nvme', 'ide'] controller_number: description: - - This parameter is used with O(disk.controller_type) for specifying controller bus number. - - For O(disk.controller_type=ide), valid value is 0 or 1. + - This parameter is used with O(disk[].controller_type) for specifying controller bus number. + - For O(disk[].controller_type=ide), valid value is 0 or 1. type: int choices: [0, 1, 2, 3] iolimit: description: - Section specifies the shares and limit for storage I/O resource. - - Not applicable when O(disk.type=vpmemdisk). + - Not applicable when O(disk[].type=vpmemdisk). suboptions: limit: description: Section specifies values for limit where the utilization of a virtual machine will not exceed, even if there are available resources. @@ -208,21 +208,21 @@ type: str choices: ['low', 'normal', 'high', 'custom'] level_value: - description: Custom value when O(disk.iolimit.shares.level=custom). + description: Custom value when O(disk[].iolimit.shares.level=custom). type: int type: dict type: dict shares: description: - Section for iolimit section tells about what are all different types of shares user can add for disk. - - Not applicable when disk O(disk.type=vpmemdisk). + - Not applicable when disk O(disk[].type=vpmemdisk). suboptions: level: description: Tells about different level for the shares section. type: str choices: ['low', 'normal', 'high', 'custom'] level_value: - description: Custom value when O(disk.shares.level=custom). + description: Custom value when O(disk[].shares.level=custom). type: int type: dict default: [] diff --git a/plugins/modules/vmware_guest_serial_port.py b/plugins/modules/vmware_guest_serial_port.py index 3c26361ebc..8b7a69f0bf 100644 --- a/plugins/modules/vmware_guest_serial_port.py +++ b/plugins/modules/vmware_guest_serial_port.py @@ -41,7 +41,7 @@ elements: dict description: - A list of backings for serial ports. - - 'O(backings.backing_type) is required to add or reconfigure or remove an existing serial port.' + - 'O(backings[].backing_type) is required to add or reconfigure or remove an existing serial port.' required: true suboptions: backing_type: @@ -53,11 +53,11 @@ - type state: description: - - O(backings.state) is required to identify whether we are adding, modifying or removing the serial port. + - O(backings[].state) is required to identify whether we are adding, modifying or removing the serial port. - If V(present), a serial port will be added or modified. - If V(absent), an existing serial port will be removed. - - If an existing serial port to modify or remove, O(backings.backing_type) and either of O(backings.service_uri) or O(backings.pipe_name) - or O(backings.device_name) or O(backings.file_path) are required. + - If an existing serial port to modify or remove, O(backings[].backing_type) and either of O(backings[].service_uri) or O(backings[].pipe_name) + or O(backings[].device_name) or O(backings[].file_path) are required. choices: - present - absent @@ -71,12 +71,12 @@ pipe_name: description: - Pipe name for the host pipe. - - Required when O(backings.backing_type=pipe). + - Required when O(backings[].backing_type=pipe). type: str endpoint: description: - When you use serial port pipe backing to connect a virtual machine to another process, you must define the endpoints. - - Required when O(backings.backing_type=pipe). + - Required when O(backings[].backing_type=pipe). type: str choices: - client @@ -85,29 +85,29 @@ no_rx_loss: description: - Enables optimized data transfer over the pipe. - - Required when O(backings.backing_type=pipe). + - Required when O(backings[].backing_type=pipe). type: bool default: false service_uri: description: - - Identifies the local host or a system on the network, depending on the value of O(backings.direction). + - Identifies the local host or a system on the network, depending on the value of O(backings[].direction). - If you use the virtual machine as a server, the URI identifies the host on which the virtual machine runs. - In this case, the host name part of the URI should be empty, or it should specify the address of the local host. - If you use the virtual machine as a client, the URI identifies the remote system on the network. - - Required when O(backings.backing_type=pipe). + - Required when O(backings[].backing_type=pipe). type: str proxy_uri: description: - - Identifies a vSPC proxy service that provides network access to the O(backings.service_uri). + - Identifies a vSPC proxy service that provides network access to the O(backings[].service_uri). - If you specify a proxy URI, the virtual machine initiates a connection with the proxy service and forwards the serviceURI and direction to the proxy. - - The C(Use Virtual Serial Port Concentrator) option is automatically enabled when O(backings.proxy_uri) is set. + - The C(Use Virtual Serial Port Concentrator) option is automatically enabled when O(backings[].proxy_uri) is set. type: str version_added: '3.7.0' direction: description: - The direction of the connection. - - Required when O(backings.backing_type=network). + - Required when O(backings[].backing_type=network). type: str choices: - client @@ -116,12 +116,12 @@ device_name: description: - Serial device absolutely path. - - Required when O(backings.backing_type=device). + - Required when O(backings[].backing_type=device). type: str file_path: description: - File path for the host file used in this backing. Fully qualified path is required, like /. - - Required when O(backings.backing_type=file). + - Required when O(backings[].backing_type=file). type: str extends_documentation_fragment: - community.vmware.vmware.documentation