[Part #5] Ensures the modules documentation follows the correct forma…

…ts (#2087) (#2242)

This is a backport of PR #2087 as merged into main (7a487f5).
SUMMARY

Ensures the modules documentation follows the correct formats

ISSUE TYPE


Bugfix Pull Request
Docs Pull Request
Feature Pull Request
New Module Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

Reviewed-by: Mark Chappell

changelogs/fragments/documentation_update_5.yml

@@ -0,0 +1,2 @@
+trivial:
+  - "Part #5 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)."

plugins/modules/kms_key.py

@@ -12,7 +12,7 @@
 description:
   - Manage role/user access to a KMS key.
   - Not designed for encrypting/decrypting.
-  - Prior to release 5.0.0 this module was called C(community.aws.aws_kms).
+  - Prior to release 5.0.0 this module was called M(community.aws.aws_kms).
     The usage did not change.
   - This module was originally added to C(community.aws) in release 1.0.0.
 options:
@@ -21,18 +21,18 @@
       - An alias for a key.
       - For safety, even though KMS does not require keys to have an alias, this module expects all
         new keys to be given an alias to make them easier to manage. Existing keys without an alias
-        may be referred to by I(key_id). Use M(amazon.aws.kms_key_info) to find key ids.
-      - Note that passing a I(key_id) and I(alias) will only cause a new alias to be added, an alias will never be renamed.
-      - The C(alias/) prefix is optional.
-      - Required if I(key_id) is not given.
+        may be referred to by O(key_id). Use M(amazon.aws.kms_key_info) to find key ids.
+      - Note that passing a O(key_id) and O(alias) will only cause a new alias to be added, an alias will never be renamed.
+      - The V(alias/) prefix is optional.
+      - Required if O(key_id) is not given.
     required: false
     aliases:
       - key_alias
     type: str
   key_id:
     description:
       - Key ID or ARN of the key.
-      - One of I(alias) or I(key_id) are required.
+      - One of O(alias) or O(key_id) are required.
     required: false
     aliases:
       - key_arn
@@ -45,17 +45,17 @@
   state:
     description:
       - Whether a key should be present or absent.
-      - Note that making an existing key C(absent) only schedules a key for deletion.
-      - Passing a key that is scheduled for deletion with I(state=present) will cancel key deletion.
-    required: False
+      - Note that making an existing key V(absent) only schedules a key for deletion.
+      - Passing a key that is scheduled for deletion with O(state=present) will cancel key deletion.
+    required: false
     choices:
       - present
       - absent
     default: present
     type: str
   enabled:
     description: Whether or not a key is enabled.
-    default: True
+    default: true
     type: bool
   description:
     description:
@@ -65,30 +65,30 @@
   multi_region:
     description:
       -  Whether to create a multi-Region primary key or not.
-    default: False
+    default: false
     type: bool
     version_added: 5.5.0
   pending_window:
     description:
       - The number of days between requesting deletion of the CMK and when it will actually be deleted.
-      - Only used when I(state=absent) and the CMK has not yet been deleted.
-      - Valid values are between 7 and 30 (inclusive).
+      - Only used when O(state=absent) and the CMK has not yet been deleted.
+      - Valid values are between V(7) and V(30) (inclusive).
       - 'See also: U(https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html#KMS-ScheduleKeyDeletion-request-PendingWindowInDays)'
     type: int
     aliases: ['deletion_delay']
     version_added: 1.4.0
     version_added_collection: community.aws
   purge_grants:
     description:
-      - Whether the I(grants) argument should cause grants not in the list to be removed.
-    default: False
+      - Whether the O(grants) argument should cause grants not in the list to be removed.
+    default: false
     type: bool
   grants:
     description:
-      - A list of grants to apply to the key. Each item must contain I(grantee_principal).
-        Each item can optionally contain I(retiring_principal), I(operations), I(constraints),
-        I(name).
-      - I(grantee_principal) and I(retiring_principal) must be ARNs
+      - A list of grants to apply to the key. Each item must contain O(grants.grantee_principal).
+        Each item can optionally contain O(grants.retiring_principal), O(grants.operations), O(grants.constraints),
+        O(grants.name).
+      - O(grants.grantee_principal) and O(grants.retiring_principal) must be ARNs.
       - 'For full documentation of suboptions see the boto3 documentation:'
       - 'U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant)'
     type: list
@@ -111,14 +111,19 @@
                       'CreateGrant', 'RetireGrant', 'DescribeKey', 'Verify', 'Sign']
         constraints:
             description:
-              - Constraints is a dict containing C(encryption_context_subset) or C(encryption_context_equals),
+              - Constraints is a dict containing V(encryption_context_subset) or V(encryption_context_equals),
                 either or both being a dict specifying an encryption context match.
                 See U(https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) or
                 U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant)
             type: dict
+        name:
+            description:
+              - A friendly name for the grant.
+              - Use this value to prevent the unintended creation of duplicate grants when retrying this request.
+            type: str
   policy:
     description:
-      - policy to apply to the KMS key.
+      - Policy to apply to the KMS key.
       - See U(https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)
     type: json
   key_spec:
@@ -256,7 +261,7 @@
 deletion_date:
   description: Date and time after which KMS deletes this KMS key.
   type: str
-  returned: when key_state is PendingDeletion
+  returned: when RV(key_state) is PendingDeletion
   sample: "2017-04-18T15:12:08.551000+10:00"
   version_added: 3.3.0
   version_added_collection: community.aws
@@ -266,7 +271,7 @@
   returned: always
   sample: "My Key for Protecting important stuff"
 enabled:
-  description: Whether the key is enabled. True if I(key_state) is C(Enabled).
+  description: Whether the key is enabled. True if RV(key_state) is V(Enabled).
   type: bool
   returned: always
   sample: false

plugins/modules/kms_key_info.py

@@ -11,7 +11,7 @@
 short_description: Gather information about AWS KMS keys
 description:
   - Gather information about AWS KMS keys including tags and grants.
-  - Prior to release 5.0.0 this module was called C(community.aws.aws_kms_info).
+  - Prior to release 5.0.0 this module was called M(community.aws.aws_kms_info).
     The usage did not change.
   - This module was originally added to C(community.aws) in release 1.0.0.
 author:
@@ -20,7 +20,7 @@
   alias:
     description:
       - Alias for key.
-      - Mutually exclusive with I(key_id) and I(filters).
+      - Mutually exclusive with O(key_id) and O(filters).
     required: false
     aliases:
       - key_alias
@@ -30,7 +30,7 @@
   key_id:
     description:
       - Key ID or ARN of the key.
-      - Mutually exclusive with I(alias) and I(filters).
+      - Mutually exclusive with O(alias) and O(filters).
     required: false
     aliases:
       - key_arn
@@ -41,13 +41,13 @@
     description:
       - A dict of filters to apply. Each dict item consists of a filter key and a filter value.
         The filters aren't natively supported by boto3, but are supported to provide similar
-        functionality to other modules. Standard tag filters (C(tag-key), C(tag-value) and
-        C(tag:tagName)) are available, as are C(key-id) and C(alias)
-      - Mutually exclusive with I(alias) and I(key_id).
+        functionality to other modules. Standard tag filters (V(tag-key), V(tag-value) and
+        V(tag:tagName)) are available, as are V(key-id) and V(alias)
+      - Mutually exclusive with O(alias) and O(key_id).
     type: dict
   pending_deletion:
     description: Whether to get full details (tags, grants etc.) of keys pending deletion.
-    default: False
+    default: false
     type: bool
 notes:
   - The C(policies) return key was removed in amazon.aws release 8.0.0.
@@ -133,7 +133,7 @@
     deletion_date:
       description: Date and time after which KMS deletes this KMS key.
       type: str
-      returned: when key_state is PendingDeletion
+      returned: when RV(kms_keys.key_state) is PendingDeletion
       sample: "2017-04-18T15:12:08.551000+10:00"
       version_added: 3.3.0
       version_added_collection: community.aws
@@ -143,7 +143,7 @@
       returned: always
       sample: "My Key for Protecting important stuff"
     enabled:
-      description: Whether the key is enabled. True if I(key_state) is C(Enabled).
+      description: Whether the key is enabled. True if RV(kms_keys.key_state) is V(Enabled).
       type: bool
       returned: always
       sample: false

plugins/modules/lambda.py

@@ -28,14 +28,14 @@
     description:
       - The runtime environment for the Lambda function you are uploading.
       - Required when creating a function. Uses parameters as described in boto3 docs.
-      - Required when I(state=present).
+      - Required when O(state=present).
       - For supported list of runtimes, see U(https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
     type: str
   role:
     description:
       - The Amazon Resource Name (ARN) of the IAM role that Lambda assumes when it executes your function to access any other Amazon Web Services (AWS)
         resources. You may use the bare ARN if the role belongs to the same AWS account.
-      - Required when I(state=present).
+      - Required when O(state=present).
     type: str
   handler:
     description:
@@ -44,19 +44,19 @@
   zip_file:
     description:
       - A .zip file containing your deployment package
-      - If I(state=present) then either I(zip_file) or I(s3_bucket) must be present.
+      - If O(state=present) then either O(zip_file) or O(s3_bucket) must be present.
     aliases: [ 'src' ]
     type: str
   s3_bucket:
     description:
       - Amazon S3 bucket name where the .zip file containing your deployment package is stored.
-      - If I(state=present) then either I(zip_file) or I(s3_bucket) must be present.
-      - I(s3_bucket) and I(s3_key) are required together.
+      - If O(state=present) then either O(zip_file) or O(s3_bucket) must be present.
+      - O(s3_bucket) and O(s3_key) are required together.
     type: str
   s3_key:
     description:
       - The Amazon S3 object (the deployment package) key name you want to upload.
-      - I(s3_bucket) and I(s3_key) are required together.
+      - O(s3_bucket) and O(s3_key) are required together.
     type: str
   s3_object_version:
     description:
@@ -81,13 +81,13 @@
     description:
       - List of subnet IDs to run Lambda function in.
       - Use this option if you need to access resources in your VPC. Leave empty if you don't want to run the function in a VPC.
-      - If set, I(vpc_security_group_ids) must also be set.
+      - If set, O(vpc_security_group_ids) must also be set.
     type: list
     elements: str
   vpc_security_group_ids:
     description:
       - List of VPC security group IDs to associate with the Lambda function.
-      - Required when I(vpc_subnet_ids) is used.
+      - Required when O(vpc_subnet_ids) is used.
     type: list
     elements: str
   environment_variables:
@@ -112,7 +112,7 @@
   architecture:
     description:
       - The instruction set architecture that the function supports.
-      - Requires one of I(s3_bucket) or I(zip_file).
+      - Requires one of O(s3_bucket) or O(zip_file).
     type: str
     choices: ['x86_64', 'arm64']
     aliases: ['architectures']
@@ -125,18 +125,18 @@
         layer_version_arn:
             description:
             - The ARN of the layer version.
-            - Mutually exclusive with I(layer_version_arn).
+            - Mutually exclusive with O(layers.layer_name).
             type: str
         layer_name:
             description:
             - The name or Amazon Resource Name (ARN) of the layer.
-            - Mutually exclusive with I(layer_version_arn).
+            - Mutually exclusive with O(layers.layer_version_arn).
             type: str
             aliases: ['layer_arn']
         version:
             description:
             - The version number.
-            - Required when I(layer_name) is provided, ignored if not.
+            - Required when O(layers.layer_name) is provided, ignored if not.
             type: int
             aliases: ['layer_version']
     type: list
@@ -146,7 +146,7 @@
     description:
       - The Amazon ECR URI of the image to use.
       - Required (alternative to runtime zip_file and s3_bucket) when creating a function.
-      - Required when I(state=present).
+      - Required when O(state=present).
     type: str
     version_added: 7.3.0
 author:
@@ -241,7 +241,7 @@
             type: str
             sample: 'S3'
 configuration:
-    description: the lambda function's configuration metadata returned by get_function in boto3
+    description: The Lambda function's configuration metadata returned by get_function in boto3.
     returned: success
     type: dict
     contains:

plugins/modules/lambda_alias.py

@@ -11,7 +11,7 @@
 short_description: Creates, updates or deletes AWS Lambda function aliases
 description:
   - This module allows the management of AWS Lambda functions aliases via the Ansible
-    framework.  It is idempotent and supports "Check" mode.    Use module M(amazon.aws.lambda) to manage the lambda function
+    framework. It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda function
     itself and M(amazon.aws.lambda_event) to manage event source mappings.
   - This module was originally added to C(community.aws) in release 1.0.0.
 
@@ -43,7 +43,7 @@
   function_version:
     description:
       -  Version associated with the Lambda function alias.
-         A value of 0 (or omitted parameter) sets the alias to the $LATEST version.
+         A value of V(0) (or omitted parameter) sets the alias to the $LATEST version.
     aliases: ['version']
     type: int
     default: 0
@@ -119,22 +119,22 @@
 RETURN = r"""
 ---
 alias_arn:
-    description: Full ARN of the function, including the alias
+    description: Full ARN of the function, including the alias.
     returned: success
     type: str
     sample: arn:aws:lambda:us-west-2:123456789012:function:myFunction:dev
 description:
-    description: A short description of the alias
+    description: A short description of the alias.
     returned: success
     type: str
-    sample: The development stage for my hot new app
+    sample: The development stage for my hot new app.
 function_version:
-    description: The qualifier that the alias refers to
+    description: The qualifier that the alias refers to.
     returned: success
     type: str
     sample: $LATEST
 name:
-    description: The name of the alias assigned
+    description: The name of the alias assigned.
     returned: success
     type: str
     sample: dev

plugins/modules/lambda_event.py

@@ -13,7 +13,7 @@
   - This module allows the management of AWS Lambda function event source mappings such as DynamoDB and Kinesis stream
     events via the Ansible framework. These event source mappings are relevant only in the AWS Lambda pull model, where
     AWS Lambda invokes the function.
-    It is idempotent and supports "Check" mode.  Use module M(amazon.aws.lambda) to manage the lambda
+    It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda
     function itself and M(amazon.aws.lambda_alias) to manage function aliases.
   - This module was originally added to C(community.aws) in release 1.0.0.
 
@@ -36,19 +36,19 @@
   alias:
     description:
       - Name of the function alias.
-      - Mutually exclusive with I(version).
+      - Mutually exclusive with O(version).
     type: str
   version:
     description:
       - Version of the Lambda function.
-      - Mutually exclusive with I(alias).
+      - Mutually exclusive with O(alias).
     type: int
     default: 0
   event_source:
     description:
       - Source of the event that triggers the lambda function.
-      - For DynamoDB and Kinesis events, select C(stream)
-      - For SQS queues, select C(sqs)
+      - For DynamoDB and Kinesis events, select V(stream).
+      - For SQS queues, select V(sqs).
     default: stream
     choices: ['stream', 'sqs']
     type: str
@@ -80,7 +80,7 @@
       starting_position:
         description:
           - The position in the stream where AWS Lambda should start reading.
-          - Required when I(event_source=stream).
+          - Required when O(event_source=stream).
         choices: [TRIM_HORIZON,LATEST]
         type: str
       function_response_types: