[PR #9422/ed092956 backport][stable-10] [a-n]*.py: normalize doc_frag…

…ments (#9428) [a-n]*.py: normalize doc_fragments (#9422) * [a-n]*.py: normalize doc_fragments * Update plugins/doc_fragments/ldap.py Co-authored-by: Felix Fontein <[email protected]> * Update plugins/doc_fragments/ldap.py Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]> (cherry picked from commit ed09295) Co-authored-by: Alexei Znamensky <[email protected]>
ansible-collections · Dec 27, 2024 · 7006238 · 7006238
1 parent 31f57b9
commit 7006238
Show file tree

Hide file tree

Showing 20 changed files with 346 additions and 359 deletions.
diff --git a/plugins/doc_fragments/alicloud.py b/plugins/doc_fragments/alicloud.py
@@ -11,75 +11,73 @@
 class ModuleDocFragment(object):
 
     # Alicloud only documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   alicloud_access_key:
     description:
-      - Alibaba Cloud access key. If not set then the value of environment variable E(ALICLOUD_ACCESS_KEY),
-        E(ALICLOUD_ACCESS_KEY_ID) will be used instead.
+      - Alibaba Cloud access key. If not set then the value of environment variable E(ALICLOUD_ACCESS_KEY), E(ALICLOUD_ACCESS_KEY_ID)
+        will be used instead.
     aliases: ['access_key_id', 'access_key']
     type: str
   alicloud_secret_key:
     description:
-      - Alibaba Cloud secret key. If not set then the value of environment variable E(ALICLOUD_SECRET_KEY),
-        E(ALICLOUD_SECRET_ACCESS_KEY) will be used instead.
+      - Alibaba Cloud secret key. If not set then the value of environment variable E(ALICLOUD_SECRET_KEY), E(ALICLOUD_SECRET_ACCESS_KEY)
+        will be used instead.
     aliases: ['secret_access_key', 'secret_key']
     type: str
   alicloud_region:
     description:
-      - The Alibaba Cloud region to use. If not specified then the value of environment variable
-        E(ALICLOUD_REGION), E(ALICLOUD_REGION_ID) will be used instead.
+      - The Alibaba Cloud region to use. If not specified then the value of environment variable E(ALICLOUD_REGION), E(ALICLOUD_REGION_ID)
+        will be used instead.
     aliases: ['region', 'region_id']
     required: true
     type: str
   alicloud_security_token:
     description:
-      - The Alibaba Cloud security token. If not specified then the value of environment variable
-        E(ALICLOUD_SECURITY_TOKEN) will be used instead.
+      - The Alibaba Cloud security token. If not specified then the value of environment variable E(ALICLOUD_SECURITY_TOKEN)
+        will be used instead.
     aliases: ['security_token']
     type: str
   alicloud_assume_role:
     description:
       - If provided with a role ARN, Ansible will attempt to assume this role using the supplied credentials.
-      - The nested assume_role block supports C(alicloud_assume_role_arn), C(alicloud_assume_role_session_name),
-        C(alicloud_assume_role_session_expiration) and C(alicloud_assume_role_policy).
+      - The nested assume_role block supports C(alicloud_assume_role_arn), C(alicloud_assume_role_session_name), C(alicloud_assume_role_session_expiration)
+        and C(alicloud_assume_role_policy).
     type: dict
     aliases: ['assume_role']
   alicloud_assume_role_arn:
     description:
-      - 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.
+      - 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']
     type: str
   alicloud_assume_role_session_name:
     description:
-      - The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted,
-        'ansible' is passed to the AssumeRole call as session name. It supports environment variable
-        E(ALICLOUD_ASSUME_ROLE_SESSION_NAME).
+      - The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted, 'ansible' is passed to
+        the AssumeRole call as session name. It supports environment variable E(ALICLOUD_ASSUME_ROLE_SESSION_NAME).
     aliases: ['assume_role_session_name']
     type: str
   alicloud_assume_role_session_expiration:
     description:
-      - 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).
+      - 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']
     type: int
   ecs_role_name:
     description:
-      - The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control'
-        section of the Alibaba Cloud console.
-      - If you're running Ansible from an ECS instance with RAM Instance using RAM Role, Ansible will just access the
-        metadata U(http://100.100.100.200/latest/meta-data/ram/security-credentials/<ecs_role_name>) to obtain the STS
-        credential. This is a preferred approach over any other when running in ECS as you can avoid hard coding
-        credentials. Instead these are leased on-the-fly by Ansible which reduces the chance of leakage.
+      - The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control' section
+        of the Alibaba Cloud console.
+      - If you are running Ansible from an ECS instance with RAM Instance using RAM Role, Ansible will just access the metadata
+        U(http://100.100.100.200/latest/meta-data/ram/security-credentials/<ecs_role_name>) to obtain the STS credential.
+        This is a preferred approach over any other when running in ECS as you can avoid hard coding credentials. Instead
+        these are leased on-the-fly by Ansible which reduces the chance of leakage.
     aliases: ['role_name']
     type: str
   profile:
     description:
-      - This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the
-        E(ALICLOUD_PROFILE) environment variable.
+      - This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the E(ALICLOUD_PROFILE)
+        environment variable.
     type: str
   shared_credentials_file:
     description:
@@ -88,22 +86,14 @@ class ModuleDocFragment(object):
       - If this is not set and a profile is specified, C(~/.aliyun/config.json) will be used.
     type: str
 author:
-    - "He Guimin (@xiaozhu36)"
+  - "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
-    E(ALICLOUD_ACCESS_KEY) or E(ALICLOUD_ACCESS_KEY_ID),
-    E(ALICLOUD_SECRET_KEY) or E(ALICLOUD_SECRET_ACCESS_KEY),
-    E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID),
-    E(ALICLOUD_SECURITY_TOKEN),
-    E(ALICLOUD_ECS_ROLE_NAME),
-    E(ALICLOUD_SHARED_CREDENTIALS_FILE),
-    E(ALICLOUD_PROFILE),
-    E(ALICLOUD_ASSUME_ROLE_ARN),
-    E(ALICLOUD_ASSUME_ROLE_SESSION_NAME),
-    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
-'''
+  - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
+    E(ALICLOUD_ACCESS_KEY) or E(ALICLOUD_ACCESS_KEY_ID), E(ALICLOUD_SECRET_KEY) or E(ALICLOUD_SECRET_ACCESS_KEY), E(ALICLOUD_REGION)
+    or E(ALICLOUD_REGION_ID), E(ALICLOUD_SECURITY_TOKEN), E(ALICLOUD_ECS_ROLE_NAME), E(ALICLOUD_SHARED_CREDENTIALS_FILE),
+    E(ALICLOUD_PROFILE), E(ALICLOUD_ASSUME_ROLE_ARN), E(ALICLOUD_ASSUME_ROLE_SESSION_NAME), 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.
+"""
diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
@@ -11,22 +11,22 @@
 class ModuleDocFragment(object):
 
     # Standard documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options: {}
 attributes:
-    check_mode:
-      description: Can run in C(check_mode) and return changed status prediction without modifying target.
-    diff_mode:
-      description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
-'''
+  check_mode:
+    description: Can run in C(check_mode) and return changed status prediction without modifying target.
+  diff_mode:
+    description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+"""
 
-    PLATFORM = r'''
+    PLATFORM = r"""
 options: {}
 attributes:
-    platform:
-      description: Target OS/families that can be operated against.
-      support: N/A
-'''
+  platform:
+    description: Target OS/families that can be operated against.
+    support: N/A
+"""
 
     # Should be used together with the standard fragment
     INFO_MODULE = r'''
@@ -42,23 +42,23 @@ class ModuleDocFragment(object):
         - This action does not modify state.
 '''
 
-    CONN = r'''
+    CONN = r"""
 options: {}
 attributes:
-    become:
-      description: Is usable alongside C(become) keywords.
-    connection:
-      description: Uses the target's configured connection information to execute code on it.
-    delegation:
-      description: Can be used in conjunction with C(delegate_to) and related keywords.
-'''
+  become:
+    description: Is usable alongside C(become) keywords.
+  connection:
+    description: Uses the target's configured connection information to execute code on it.
+  delegation:
+    description: Can be used in conjunction with C(delegate_to) and related keywords.
+"""
 
-    FACTS = r'''
+    FACTS = r"""
 options: {}
 attributes:
-    facts:
-      description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
-'''
+  facts:
+    description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+"""
 
     # Should be used together with the standard fragment and the FACTS fragment
     FACTS_MODULE = r'''
@@ -76,18 +76,18 @@ class ModuleDocFragment(object):
       support: full
 '''
 
-    FILES = r'''
+    FILES = r"""
 options: {}
 attributes:
-    safe_file_operations:
-      description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
-'''
+  safe_file_operations:
+    description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+"""
 
-    FLOW = r'''
+    FLOW = r"""
 options: {}
 attributes:
-    action:
-      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
-    async:
-      description: Supports being used with the C(async) keyword.
-'''
+  action:
+    description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+  async:
+    description: Supports being used with the C(async) keyword.
+"""
diff --git a/plugins/doc_fragments/auth_basic.py b/plugins/doc_fragments/auth_basic.py
@@ -10,7 +10,7 @@
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   api_url:
     description:
@@ -29,4 +29,4 @@ class ModuleDocFragment(object):
       - Whether or not to validate SSL certs when supplying a HTTPS endpoint.
     type: bool
     default: true
-'''
+"""
diff --git a/plugins/doc_fragments/bitbucket.py b/plugins/doc_fragments/bitbucket.py
@@ -11,7 +11,7 @@
 class ModuleDocFragment(object):
 
     # Standard documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   client_id:
     description:
@@ -30,7 +30,7 @@ class ModuleDocFragment(object):
       - O(ignore:username) is an alias of O(user) since community.general 6.0.0. It was an alias of O(workspace) before.
     type: str
     version_added: 4.0.0
-    aliases: [ username ]
+    aliases: [username]
   password:
     description:
       - The App password.
@@ -41,4 +41,4 @@ class ModuleDocFragment(object):
   - Bitbucket OAuth consumer key and secret can be obtained from Bitbucket profile -> Settings -> Access Management -> OAuth.
   - Bitbucket App password can be created from Bitbucket profile -> Personal Settings -> App passwords.
   - If both OAuth and Basic Auth credentials are passed, OAuth credentials take precedence.
-'''
+"""
diff --git a/plugins/doc_fragments/consul.py b/plugins/doc_fragments/consul.py
@@ -15,7 +15,7 @@ class ModuleDocFragment:
 options:
   host:
     description:
-      - Host of the consul agent, defaults to V(localhost).
+      - Host of the Consul agent.
     default: localhost
     type: str
   port:
@@ -25,18 +25,18 @@ class ModuleDocFragment:
     default: 8500
   scheme:
     description:
-      - The protocol scheme on which the consul agent is running.
-        Defaults to V(http) and can be set to V(https) for secure connections.
+      - The protocol scheme on which the Consul agent is running. Defaults to V(http) and can be set to V(https) for secure
+        connections.
     default: http
     type: str
   validate_certs:
     type: bool
     description:
-      - Whether to verify the TLS certificate of the consul agent.
+      - Whether to verify the TLS certificate of the Consul agent.
     default: true
   ca_path:
     description:
-      - The CA bundle to use for https connections
+      - The CA bundle to use for https connections.
     type: str
 """
 

diff --git a/plugins/doc_fragments/dimensiondata.py b/plugins/doc_fragments/dimensiondata.py
@@ -14,8 +14,7 @@
 class ModuleDocFragment(object):
 
     # Dimension Data doc fragment
-    DOCUMENTATION = r'''
-
+    DOCUMENTATION = r"""
 options:
   region:
     description:
@@ -48,4 +47,4 @@ class ModuleDocFragment(object):
       - This should only be used on private instances of the CloudControl API that use self-signed certificates.
     type: bool
     default: true
-'''
+"""
diff --git a/plugins/doc_fragments/dimensiondata_wait.py b/plugins/doc_fragments/dimensiondata_wait.py
@@ -14,8 +14,7 @@
 class ModuleDocFragment(object):
 
     # Dimension Data ("wait-for-completion" parameters) doc fragment
-    DOCUMENTATION = r'''
-
+    DOCUMENTATION = r"""
 options:
   wait:
     description:
@@ -34,4 +33,4 @@ class ModuleDocFragment(object):
       - Only applicable if O(wait=true).
     type: int
     default: 2
-'''
+"""
diff --git a/plugins/doc_fragments/django.py b/plugins/doc_fragments/django.py
@@ -8,7 +8,7 @@
 
 
 class ModuleDocFragment(object):
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   venv:
     description:
@@ -43,20 +43,19 @@ class ModuleDocFragment(object):
 
 notes:
   - The C(django-admin) command is always executed using the C(C) locale, and the option C(--no-color) is always passed.
-
 seealso:
   - name: django-admin and manage.py in official Django documentation
     description: >-
-      Refer to this documentation for the builtin commands and options of C(django-admin).
-      Please make sure that you select the right version of Django in the version selector on that page.
+      Refer to this documentation for the builtin commands and options of C(django-admin). Please make sure that you select
+      the right version of Django in the version selector on that page.
     link: https://docs.djangoproject.com/en/5.0/ref/django-admin/
-'''
+"""
 
-    DATABASE = r'''
+    DATABASE = r"""
 options:
   database:
     description:
       - Specify the database to be used.
     type: str
     default: default
-'''
+"""
diff --git a/plugins/doc_fragments/emc.py b/plugins/doc_fragments/emc.py
@@ -10,14 +10,14 @@
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = r'''
-options:
-  - See respective platform section for more details
+    DOCUMENTATION = r"""
+options: {}
+# See respective platform section for more details
 requirements:
   - See respective platform section for more details
 notes:
   - Ansible modules are available for EMC VNX.
-'''
+"""
 
     # Documentation fragment for VNX (emc_vnx)
     EMC_VNX = r'''