[PR #7551/a88f6f56 backport][stable-8] Clean up doc fragments a bit (#7568)

Clean up doc fragments a bit (#7551)

Clean up doc fragments a bit.

(cherry picked from commit a88f6f56c7)

Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/doc_fragments/alicloud.py

@@ -47,7 +47,7 @@ options:
     aliases: ['assume_role']
   alicloud_assume_role_arn:
     description:
-      - The Alibaba Cloud role_arn. The ARN of the role to assume. If ARN is set to an empty string,
+      - The Alibaba Cloud C(role_arn). The ARN of the role to assume. If ARN is set to an empty string,
         it does not perform role switching. It supports environment variable E(ALICLOUD_ASSUME_ROLE_ARN).
         ansible will execute with provided credentials.
     aliases: ['assume_role_arn']
@@ -61,7 +61,7 @@ options:
     type: str
   alicloud_assume_role_session_expiration:
     description:
-      - The Alibaba Cloud session_expiration. The time after which the established session for assuming
+      - The Alibaba Cloud C(session_expiration). The time after which the established session for assuming
         role expires. Valid value range 900-3600 seconds. Default to 3600 (in this case Alicloud use own default
         value). It supports environment variable E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
     aliases: ['assume_role_session_expiration']
@@ -85,12 +85,12 @@ options:
     description:
       - This is the path to the shared credentials file. It can also be sourced from the E(ALICLOUD_SHARED_CREDENTIALS_FILE)
         environment variable.
-      - If this is not set and a profile is specified,  ~/.aliyun/config.json will be used.
+      - If this is not set and a profile is specified, C(~/.aliyun/config.json) will be used.
     type: str
 author:
     - "He Guimin (@xiaozhu36)"
 requirements:
-    - "python >= 3.6"
+    - "Python >= 3.6"
 notes:
   - If parameters are not set within the module, the following
     environment variables can be used in decreasing order of precedence
@@ -103,7 +103,7 @@ notes:
     E(ALICLOUD_PROFILE),
     E(ALICLOUD_ASSUME_ROLE_ARN),
     E(ALICLOUD_ASSUME_ROLE_SESSION_NAME),
-    E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION),
+    E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
   - E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID) can be typically be used to specify the
-    ALICLOUD region, when required, but this can also be configured in the footmark config file
+    Alicloud region, when required, but this can also be configured in the footmark config file
 '''

plugins/doc_fragments/auth_basic.py

@@ -14,19 +14,19 @@ class ModuleDocFragment(object):
 options:
   api_url:
     description:
-      - The resolvable endpoint for the API
+      - The resolvable endpoint for the API.
     type: str
   api_username:
     description:
-      - The username to use for authentication against the API
+      - The username to use for authentication against the API.
     type: str
   api_password:
     description:
-      - The password to use for authentication against the API
+      - The password to use for authentication against the API.
     type: str
   validate_certs:
     description:
-      - Whether or not to validate SSL certs when supplying a https endpoint.
+      - Whether or not to validate SSL certs when supplying a HTTPS endpoint.
     type: bool
     default: true
 '''

plugins/doc_fragments/dimensiondata.py

@@ -20,10 +20,10 @@ options:
   region:
     description:
       - The target region.
-      - Regions are defined in Apache libcloud project [libcloud/common/dimensiondata.py]
+      - Regions are defined in Apache libcloud project [libcloud/common/dimensiondata.py].
-      - They are also listed in U(https://libcloud.readthedocs.io/en/latest/compute/drivers/dimensiondata.html)
+      - They are also listed in U(https://libcloud.readthedocs.io/en/latest/compute/drivers/dimensiondata.html).
-      - Note that the default value "na" stands for "North America".
+      - Note that the default value C(na) stands for "North America".
-      - The module prepends 'dd-' to the region choice.
+      - The module prepends C(dd-) to the region choice.
     type: str
     default: na
   mcp_user:

plugins/doc_fragments/dimensiondata_wait.py

@@ -34,4 +34,4 @@ options:
       - Only applicable if O(wait=true).
     type: int
     default: 2
-    '''
+'''

plugins/doc_fragments/emc.py

@@ -39,8 +39,7 @@ options:
         default: sysadmin
 requirements:
   - An EMC VNX Storage device.
-  - Ansible 2.7.
+  - storops (0.5.10 or greater). Install using C(pip install storops).
-  - storops (0.5.10 or greater). Install using 'pip install storops'.
 notes:
-  - The modules prefixed with emc_vnx are built to support the EMC VNX storage platform.
+  - The modules prefixed with C(emc_vnx) are built to support the EMC VNX storage platform.
 '''

plugins/doc_fragments/hwc.py

@@ -19,8 +19,8 @@ options:
         required: true
     user:
         description:
-            - The user name to login with (currently only user names are
+            - The user name to login with.
-              supported, and not user IDs).
+            - Currently only user names are supported, and not user IDs.
         type: str
         required: true
     password:
@@ -31,14 +31,13 @@ options:
     domain:
         description:
             - The name of the Domain to scope to (Identity v3).
-              (currently only domain names are supported, and not domain IDs).
+            - Currently only domain names are supported, and not domain IDs.
         type: str
         required: true
     project:
         description:
             - The name of the Tenant (Identity v2) or Project (Identity v3).
-              (currently only project names are supported, and not
+            - Currently only project names are supported, and not project IDs.
-               project IDs).
         type: str
         required: true
     region:
@@ -47,20 +46,20 @@ options:
         type: str
     id:
         description:
-            - The id of resource to be managed.
+            - The ID of resource to be managed.
         type: str
 notes:
   - For authentication, you can set identity_endpoint using the
-    E(ANSIBLE_HWC_IDENTITY_ENDPOINT) env variable.
+    E(ANSIBLE_HWC_IDENTITY_ENDPOINT) environment variable.
   - For authentication, you can set user using the
-    E(ANSIBLE_HWC_USER) env variable.
+    E(ANSIBLE_HWC_USER) environment variable.
-  - For authentication, you can set password using the E(ANSIBLE_HWC_PASSWORD) env
+  - For authentication, you can set password using the E(ANSIBLE_HWC_PASSWORD) environment
     variable.
-  - For authentication, you can set domain using the E(ANSIBLE_HWC_DOMAIN) env
+  - For authentication, you can set domain using the E(ANSIBLE_HWC_DOMAIN) environment
     variable.
-  - For authentication, you can set project using the E(ANSIBLE_HWC_PROJECT) env
+  - For authentication, you can set project using the E(ANSIBLE_HWC_PROJECT) environment
     variable.
-  - For authentication, you can set region using the E(ANSIBLE_HWC_REGION) env variable.
+  - For authentication, you can set region using the E(ANSIBLE_HWC_REGION) environment variable.
   - Environment variables values will only be used if the playbook values are
     not set.
 '''

plugins/doc_fragments/ibm_storage.py

@@ -31,8 +31,7 @@ options:
         required: true
 notes:
   - This module requires pyxcli python library.
-    Use 'pip install pyxcli' in order to get pyxcli.
+    Use C(pip install pyxcli) in order to get pyxcli.
 requirements:
-  - python >= 2.7
   - pyxcli
 '''

plugins/doc_fragments/influxdb.py

@@ -16,32 +16,29 @@ options:
   hostname:
     description:
     - The hostname or IP address on which InfluxDB server is listening.
-    - Since Ansible 2.5, defaulted to localhost.
     type: str
     default: localhost
   username:
     description:
     - Username that will be used to authenticate against InfluxDB server.
-    - Alias O(login_username) added in Ansible 2.5.
     type: str
     default: root
     aliases: [ login_username ]
   password:
     description:
     - Password that will be used to authenticate against InfluxDB server.
-    - Alias O(login_password) added in Ansible 2.5.
     type: str
     default: root
     aliases: [ login_password ]
   port:
     description:
-    - The port on which InfluxDB server is listening
+    - The port on which InfluxDB server is listening.
     type: int
     default: 8086
   path:
     description:
-    - The path on which InfluxDB server is accessible
+    - The path on which InfluxDB server is accessible.
-    - Only available when using python-influxdb >= 5.1.0
+    - Only available when using python-influxdb >= 5.1.0.
     type: str
     default: ''
     version_added: '0.2.0'
@@ -64,7 +61,7 @@ options:
     description:
     - Number of retries client will try before aborting.
     - V(0) indicates try until success.
-    - Only available when using python-influxdb >= 4.1.0
+    - Only available when using python-influxdb >= 4.1.0.
     type: int
     default: 3
   use_udp:

plugins/doc_fragments/ipa.py

@@ -18,7 +18,6 @@ options:
     - Port of FreeIPA / IPA server.
     - If the value is not specified in the task, the value of environment variable E(IPA_PORT) will be used instead.
     - If both the environment variable E(IPA_PORT) and the value are not specified in the task, then default value is set.
-    - Environment variable fallback mechanism is added in Ansible 2.5.
     type: int
     default: 443
   ipa_host:
@@ -26,9 +25,8 @@ options:
     - IP or hostname of IPA server.
     - If the value is not specified in the task, the value of environment variable E(IPA_HOST) will be used instead.
     - If both the environment variable E(IPA_HOST) and the value are not specified in the task, then DNS will be used to try to discover the FreeIPA server.
-    - The relevant entry needed in FreeIPA is the 'ipa-ca' entry.
+    - The relevant entry needed in FreeIPA is the C(ipa-ca) entry.
     - If neither the DNS entry, nor the environment E(IPA_HOST), nor the value are available in the task, then the default value will be used.
-    - Environment variable fallback mechanism is added in Ansible 2.5.
     type: str
     default: ipa.example.com
   ipa_user:
@@ -36,7 +34,6 @@ options:
     - Administrative account used on IPA server.
     - If the value is not specified in the task, the value of environment variable E(IPA_USER) will be used instead.
     - If both the environment variable E(IPA_USER) and the value are not specified in the task, then default value is set.
-    - Environment variable fallback mechanism is added in Ansible 2.5.
     type: str
     default: admin
   ipa_pass:
@@ -47,14 +44,12 @@ options:
     - If the environment variable E(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate to the FreeIPA server.
     - If the environment variable E(KRB5_CLIENT_KTNAME) is available, and E(KRB5CCNAME) is not; the module will use this kerberos keytab to authenticate.
     - If GSSAPI is not available, the usage of O(ipa_pass) is required.
-    - Environment variable fallback mechanism is added in Ansible 2.5.
     type: str
   ipa_prot:
     description:
     - Protocol used by IPA server.
     - If the value is not specified in the task, the value of environment variable E(IPA_PROT) will be used instead.
     - If both the environment variable E(IPA_PROT) and the value are not specified in the task, then default value is set.
-    - Environment variable fallback mechanism is added in Ansible 2.5.
     type: str
     choices: [ http, https ]
     default: https

plugins/doc_fragments/keycloak.py

@@ -69,6 +69,7 @@ options:
         type: int
         default: 10
         version_added: 4.5.0
+
     http_agent:
         description:
             - Configures the HTTP User-Agent header.

plugins/doc_fragments/lxca_common.py

@@ -30,7 +30,7 @@ options:
 
   auth_url:
     description:
-    - lxca https full web address
+    - lxca HTTPS full web address.
     type: str
     required: true
 
@@ -38,7 +38,6 @@ requirements:
   - pylxca
 
 notes:
-  -  Additional detail about pylxca can be found at U(https://github.com/lenovo/pylxca)
+  - Additional detail about pylxca can be found at U(https://github.com/lenovo/pylxca).
-  -  Playbooks using these modules can be found at U(https://github.com/lenovo/ansible.lenovo-lxca)
+  - Playbooks using these modules can be found at U(https://github.com/lenovo/ansible.lenovo-lxca).
-  -  Check mode is not supported.
 '''

plugins/doc_fragments/oneview.py

@@ -15,7 +15,7 @@ class ModuleDocFragment(object):
 options:
     config:
         description:
-        - Path to a .json configuration file containing the OneView client configuration.
+        - Path to a JSON configuration file containing the OneView client configuration.
           The configuration file is optional and when used should be present in the host running the ansible commands.
           If the file path is not provided, the configuration will be loaded from environment variables.
           For links to example configuration files or how to use the environment variables verify the notes section.
@@ -42,7 +42,7 @@ options:
         type: str
 
 requirements:
-  - python >= 2.7.9
+  - Python >= 2.7.9
 
 notes:
     - "A sample configuration file for the config parameter can be found at:
@@ -70,11 +70,11 @@ options:
 options:
     params:
         description:
-        - List of params to delimit, filter and sort the list of resources.
+        - List of parameters to delimit, filter and sort the list of resources.
-        - "params allowed:
+        - "Parameter keys allowed are:"
-            - C(start): The first item to return, using 0-based indexing.
+        - "C(start): The first item to return, using 0-based indexing."
-            - C(count): The number of resources to return.
+        - "C(count): The number of resources to return."
-            - C(filter): A general filter/query string to narrow the list of items returned.
+        - "C(filter): A general filter/query string to narrow the list of items returned."
-            - C(sort): The sort order of the returned data set."
+        - "C(sort): The sort order of the returned data set."
         type: dict
 '''

plugins/doc_fragments/online.py

@@ -20,7 +20,7 @@ options:
     aliases: [ oauth_token ]
   api_url:
     description:
-      - Online API URL
+      - Online API URL.
     type: str
     default: 'https://api.online.net'
     aliases: [ base_url ]
@@ -36,7 +36,7 @@ options:
     type: bool
     default: true
 notes:
-  - Also see the API documentation on U(https://console.online.net/en/api/)
+  - Also see the API documentation on U(https://console.online.net/en/api/).
   - If O(api_token) is not set within the module, the following
     environment variables can be used in decreasing order of precedence
     E(ONLINE_TOKEN), E(ONLINE_API_KEY), E(ONLINE_OAUTH_TOKEN), E(ONLINE_API_TOKEN).

plugins/doc_fragments/openswitch.py

@@ -64,7 +64,7 @@ options:
     description:
       - Configures the transport connection to use when connecting to the
         remote device.  The transport argument supports connectivity to the
-        device over ssh, cli or REST.
+        device over SSH (V(ssh)), CLI (V(cli)), or REST (V(rest)).
     required: true
     type: str
     choices: [ cli, rest, ssh ]

plugins/doc_fragments/oracle.py

@@ -10,22 +10,21 @@ __metaclass__ = type
 class ModuleDocFragment(object):
     DOCUMENTATION = """
     requirements:
-        - "python >= 2.7"
+        - Python SDK for Oracle Cloud Infrastructure U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io)
-        -  Python SDK for Oracle Cloud Infrastructure U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io)
     notes:
-        - For OCI python sdk configuration, please refer to
+        - For OCI Python SDK configuration, please refer to
-          U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html)
+          U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html).
     options:
         config_file_location:
             description:
                 - Path to configuration file. If not set then the value of the E(OCI_CONFIG_FILE) environment variable,
-                  if any, is used. Otherwise, defaults to ~/.oci/config.
+                  if any, is used. Otherwise, defaults to C(~/.oci/config).
             type: str
         config_profile_name:
             description:
                 - The profile to load from the config file referenced by O(config_file_location). If not set, then the
                   value of the E(OCI_CONFIG_PROFILE) environment variable, if any, is used. Otherwise, defaults to the
-                  "DEFAULT" profile in O(config_file_location).
+                  C(DEFAULT) profile in O(config_file_location).
             default: "DEFAULT"
             type: str
         api_user:
@@ -70,8 +69,8 @@ class ModuleDocFragment(object):
             description:
                 - OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is
                   used. This option is required if the tenancy OCID is not specified through a configuration file
-                  (See O(config_file_location)). To get the tenancy OCID, please refer
+                  (See O(config_file_location)). To get the tenancy OCID, please refer to
-                  U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm)
+                  U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
             type: str
         region:
             description:

plugins/doc_fragments/oracle_wait_options.py

@@ -21,7 +21,7 @@ class ModuleDocFragment(object):
         wait_until:
             description: The lifecycle state to wait for the resource to transition into when O(wait=true). By default,
                          when O(wait=true), we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/
-                         RUNNING applicable lifecycle state during create operation & to get into DELETED/DETACHED/
+                         RUNNING applicable lifecycle state during create operation and to get into DELETED/DETACHED/
                          TERMINATED lifecycle state during delete operation.
             type: str
     """

plugins/doc_fragments/purestorage.py

@@ -32,11 +32,10 @@ options:
       - FlashBlade API token for admin privileged user.
     type: str
 notes:
-  - This module requires the C(purity_fb) Python library
+  - This module requires the C(purity_fb) Python library.
   - You must set E(PUREFB_URL) and E(PUREFB_API) environment variables
-    if O(fb_url) and O(api_token) arguments are not passed to the module directly
+    if O(fb_url) and O(api_token) arguments are not passed to the module directly.
 requirements:
-  - python >= 2.7
   - purity_fb >= 1.1
 '''
 
@@ -54,10 +53,9 @@ options:
     type: str
     required: true
 notes:
-  - This module requires the C(purestorage) Python library
+  - This module requires the C(purestorage) Python library.
   - You must set E(PUREFA_URL) and E(PUREFA_API) environment variables
-    if O(fa_url) and O(api_token) arguments are not passed to the module directly
+    if O(fa_url) and O(api_token) arguments are not passed to the module directly.
 requirements:
-  - python >= 2.7
   - purestorage
 '''

plugins/doc_fragments/rackspace.py

@@ -43,15 +43,14 @@ options:
     type: bool
     aliases: [ verify_ssl ]
 requirements:
-  - python >= 2.6
   - pyrax
 notes:
   - The following environment variables can be used, E(RAX_USERNAME),
     E(RAX_API_KEY), E(RAX_CREDS_FILE), E(RAX_CREDENTIALS), E(RAX_REGION).
   - E(RAX_CREDENTIALS) and E(RAX_CREDS_FILE) point to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
+    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating).
-  - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file
+  - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file.
-  - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+  - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...).
 '''
 
     # Documentation fragment including attributes to enable communication
@@ -67,7 +66,7 @@ options:
     type: str
     description:
       - The URI of the authentication service.
-      - If not specified will be set to U(https://identity.api.rackspacecloud.com/v2.0/)
+      - If not specified will be set to U(https://identity.api.rackspacecloud.com/v2.0/).
   credentials:
     type: path
     description:
@@ -110,13 +109,12 @@ deprecated:
   why: This module relies on the deprecated package pyrax.
   alternative: Use the Openstack modules instead.
 requirements:
-  - python >= 2.6
   - pyrax
 notes:
   - The following environment variables can be used, E(RAX_USERNAME),
     E(RAX_API_KEY), E(RAX_CREDS_FILE), E(RAX_CREDENTIALS), E(RAX_REGION).
   - E(RAX_CREDENTIALS) and E(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
+    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating).
-  - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file
+  - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file.
-  - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+  - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...).
 '''

plugins/doc_fragments/scaleway.py

@@ -42,7 +42,7 @@ options:
     type: bool
     default: true
 notes:
-  - Also see the API documentation on U(https://developer.scaleway.com/)
+  - Also see the API documentation on U(https://developer.scaleway.com/).
   - If O(api_token) is not set within the module, the following
     environment variables can be used in decreasing order of precedence
     E(SCW_TOKEN), E(SCW_API_KEY), E(SCW_OAUTH_TOKEN) or E(SCW_API_TOKEN).

plugins/doc_fragments/utm.py

@@ -14,7 +14,7 @@ options:
     headers:
         description:
           - A dictionary of additional headers to be sent to POST and PUT requests.
-          - Is needed for some modules
+          - Is needed for some modules.
         type: dict
         required: false
         default: {}
@@ -30,8 +30,9 @@ options:
         default: 4444
     utm_token:
         description:
-          - "The token used to identify at the REST-API. See U(https://www.sophos.com/en-us/medialibrary/\
+          - "The token used to identify at the REST-API. See
-            PDFs/documentation/UTMonAWS/Sophos-UTM-RESTful-API.pdf?la=en), Chapter 2.4.2."
+            U(https://www.sophos.com/en-us/medialibrary/PDFs/documentation/UTMonAWS/Sophos-UTM-RESTful-API.pdf?la=en),
+            Chapter 2.4.2."
         type: str
         required: true
     utm_protocol:
@@ -48,8 +49,8 @@ options:
     state:
         description:
           - The desired state of the object.
-          - V(present) will create or update an object
+          - V(present) will create or update an object.
-          - V(absent) will delete an object if it was present
+          - V(absent) will delete an object if it was present.
         type: str
         choices: [ absent, present ]
         default: present

plugins/doc_fragments/vexata.py

@@ -30,11 +30,13 @@ options:
   user:
     description:
       - Vexata API user with administrative privileges.
+      - Uses the E(VEXATA_USER) environment variable as a fallback.
     required: false
     type: str
   password:
     description:
       - Vexata API user password.
+      - Uses the E(VEXATA_PASSWORD) environment variable as a fallback.
     required: false
     type: str
   validate_certs:
@@ -48,7 +50,6 @@ options:
 requirements:
   - Vexata VX100 storage array with VXOS >= v3.5.0 on storage array
   - vexatapi >= 0.0.1
-  - python >= 2.7
+  - E(VEXATA_USER) and E(VEXATA_PASSWORD) environment variables must be set if
-  - VEXATA_USER and VEXATA_PASSWORD environment variables must be set if
     user and password arguments are not passed to the module directly.
 '''