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

@@ -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

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).

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

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.

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

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.

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

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: []

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 <datastore_name>/<file_name>.
-          - Required when O(backings.backing_type=file).
+          - Required when O(backings[].backing_type=file).
         type: str
 extends_documentation_fragment:
 - community.vmware.vmware.documentation