Update docs

plugins/callback/aws_resource_actions.py

@@ -3,7 +3,7 @@
 # (C) 2018 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
     name: aws_resource_actions
     type: aggregate
     short_description: summarizes all "resource:actions" completed
@@ -15,7 +15,7 @@
       - whitelisting in configuration - see examples section below for details.
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 example: >
   To enable, add this to your ansible.cfg file in the defaults block
     [defaults]

plugins/inventory/aws_ec2.py

@@ -15,7 +15,7 @@
   - amazon.aws.assume_role.plugins
 description:
   - Get inventory hosts from Amazon Web Services EC2.
-  - "The inventory file is a YAML configuration file and must end with C(aws_ec2.{yml|yaml}). Example: C(my_inventory.aws_ec2.yml)."
+  - The inventory file is a YAML configuration file and must end with C(aws_ec2.{yml|yaml}). For example - C(my_inventory.aws_ec2.yml).
 notes:
   - If no credentials are provided and the control node has an associated IAM instance profile then the
     role will be used for authentication.
@@ -25,7 +25,7 @@
   regions:
     description:
       - A list of regions in which to describe EC2 instances.
-      - If empty (the default) default this will include all regions, except possibly restricted ones like us-gov-west-1 and cn-north-1.
+      - If empty (the default) default this will include all regions, except possibly restricted ones like V(us-gov-west-1) and V(cn-north-1).
     type: list
     elements: str
     default: []
@@ -44,27 +44,27 @@
         description:
           - Name of the host.
         type: str
-        required: True
+        required: true
       prefix:
         description:
-          - Prefix to prepend to I(name). Same options as I(name).
-          - If I(prefix) is specified, final hostname will be I(prefix) +  I(separator) + I(name).
+          - Prefix to prepend to O(hostnames.name). Same options as O(hostnames.name).
+          - If O(hostnames.prefix) is specified, final hostname will be O(hostnames.prefix) + O(hostnames.separator) + O(hostnames.name).
         type: str
         default: ''
-        required: False
+        required: false
       separator:
         description:
-          - Value to separate I(prefix) and I(name) when I(prefix) is specified.
+          - Value to separate O(hostnames.prefix) and O(hostnames.name) when O(hostnames.prefix) is specified.
         type: str
         default: '_'
-        required: False
+        required: false
   allow_duplicated_hosts:
     description:
-      - By default, the first name that matches an entry of the I(hostnames) list is returned.
+      - By default, the first name that matches an entry of the O(hostnames) list is returned.
       - Turn this flag on if you don't mind having duplicated entries in the inventory
         and you want to get all the hostnames that match.
     type: bool
-    default: False
+    default: false
     version_added: 5.0.0
   filters:
     description:
@@ -85,7 +85,7 @@
   exclude_filters:
     description:
       - A list of filters. Any instances matching one of the filters are excluded from the result.
-      - The filters from C(exclude_filters) take priority over the C(include_filters) and C(filters) keys
+      - The filters from O(exclude_filters) take priority over the O(include_filters) and O(filters) keys.
       - Available filters are listed here U(http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options).
       - Every entry in this list triggers a search query. As such, from a performance point of view, it's better to
         keep the list as short as possible.
@@ -98,7 +98,7 @@
       - By default if a 403 (Forbidden) error code is encountered this plugin will fail.
       - You can set this option to False in the inventory config file which will allow 403 errors to be gracefully skipped.
     type: bool
-    default: True
+    default: true
   use_contrib_script_compatible_sanitization:
     description:
       - By default this plugin is using a general group name sanitization to create safe and usable group names for use in Ansible.
@@ -111,13 +111,13 @@
       - This is not the default as such names break certain functionality as not all characters are valid Python identifiers
         which group names end up being used as.
     type: bool
-    default: False
+    default: false
   use_contrib_script_compatible_ec2_tag_keys:
     description:
       - Expose the host tags with ec2_tag_TAGNAME keys like the old ec2.py inventory script.
       - The use of this feature is discouraged and we advise to migrate to the new ``tags`` structure.
     type: bool
-    default: False
+    default: false
     version_added: 1.5.0
   hostvars_prefix:
     description:
@@ -132,11 +132,11 @@
   use_ssm_inventory:
     description:
       - Enables fetching additional EC2 instance information from the AWS Systems Manager (SSM) inventory service into hostvars.
-      - By leveraging the SSM inventory data, the I(use_ssm_inventory) option provides additional details and attributes
+      - By leveraging the SSM inventory data, the O(use_ssm_inventory) option provides additional details and attributes
         about the EC2 instances in your inventory. These details can include operating system information, installed software,
         network configurations, and custom inventory attributes defined in SSM.
     type: bool
-    default: False
+    default: false
     version_added: 6.0.0
 """
 

plugins/inventory/aws_rds.py

@@ -26,11 +26,11 @@
       - By default if an AccessDenied exception is encountered this plugin will fail. You can set strict_permissions to
         False in the inventory config file which will allow the restrictions to be gracefully skipped.
     type: bool
-    default: True
+    default: true
   include_clusters:
     description: Whether or not to query for Aurora clusters as well as instances.
     type: bool
-    default: False
+    default: false
   statuses:
     description: A list of desired states for instances/clusters to be added to inventory. Set to ['all'] as a shorthand to find everything.
     type: list

plugins/lookup/aws_account_attribute.py

@@ -44,8 +44,8 @@
 RETURN = r"""
 _raw:
   description:
-    Returns a boolean when I(attribute) is check_ec2_classic. Otherwise returns the value(s) of the attribute
-    (or all attributes if one is not specified).
+    - Returns a boolean when O(attribute=check_ec2_classic). Otherwise returns the value(s) of the attribute
+      (or all attributes if one is not specified).
 """
 
 try:

plugins/lookup/aws_collection_constants.py

@@ -22,15 +22,15 @@
       - AMAZON_AWS_COLLECTION_NAME
       - COMMUNITY_AWS_COLLECTION_VERSION
       - COMMUNITY_AWS_COLLECTION_NAME
-    required: True
+    required: true
 """
 
 EXAMPLES = r"""
 """
 
 RETURN = r"""
 _raw:
-  description: value
+  description: Value.
   type: str
 """
 

plugins/lookup/aws_service_ip_ranges.py

@@ -10,17 +10,21 @@
   - James Turner (!UNKNOWN) <[email protected]>
 requirements:
   - must have public internet connectivity
-short_description: Look up the IP ranges for services provided in AWS such as EC2 and S3.
+short_description: Look up the IP ranges for services provided in AWS such as EC2 and S3
 description:
   - AWS publishes IP ranges used on the public internet by EC2, S3, CloudFront, CodeBuild, Route53, and Route53 Health Checking.
   - This module produces a list of all the ranges (by default) or can narrow down the list to the specified region or service.
 options:
   service:
-    description: 'The service to filter ranges by. Options: EC2, S3, CLOUDFRONT, CODEbUILD, ROUTE53, ROUTE53_HEALTHCHECKS'
+    description:
+      - The service to filter ranges by.
+      - Options include V(EC2), V(S3), V(CLOUDFRONT), V(CODEBUILD), V(ROUTE53), V(ROUTE53_HEALTHCHECKS).
   region:
-    description: 'The AWS region to narrow the ranges to. Examples: us-east-1, eu-west-2, ap-southeast-1'
+    description:
+      - The AWS region to narrow the ranges to. Examples include V(us-east-1), V(eu-west-2), V(ap-southeast-1).
   ipv6_prefixes:
-    description: 'When I(ipv6_prefixes=True) the lookup will return ipv6 addresses instead of ipv4 addresses'
+    description:
+      - When O(ipv6_prefixes=true) the lookup will return ipv6 addresses instead of ipv4 addresses.
     version_added: 2.1.0
 """
 
@@ -29,17 +33,17 @@
   ec2_ranges: "{{ lookup('aws_service_ip_ranges', region='ap-southeast-2', service='EC2', wantlist=True) }}"
 tasks:
   - name: "use list return option and iterate as a loop"
-    debug: msg="{% for cidr in ec2_ranges %}{{ cidr }} {% endfor %}"
+    ansible.builtin.debug: msg="{% for cidr in ec2_ranges %}{{ cidr }} {% endfor %}"
   # "52.62.0.0/15 52.64.0.0/17 52.64.128.0/17 52.65.0.0/16 52.95.241.0/24 52.95.255.16/28 54.66.0.0/16 "
 
   - name: "Pull S3 IP ranges, and print the default return style"
-    debug: msg="{{ lookup('aws_service_ip_ranges', region='us-east-1', service='S3') }}"
+    ansible.builtin.debug: msg="{{ lookup('aws_service_ip_ranges', region='us-east-1', service='S3') }}"
   # "52.92.16.0/20,52.216.0.0/15,54.231.0.0/17"
 """
 
 RETURN = r"""
 _raw:
-  description: comma-separated list of CIDR ranges
+  description: Comma-separated list of CIDR ranges.
 """
 
 import json

plugins/lookup/secretsmanager_secret.py

@@ -13,98 +13,97 @@
   - Look up secrets stored in AWS Secrets Manager provided the caller
     has the appropriate permissions to read the secret.
   - Lookup is based on the secret's I(Name) value.
-  - Optional parameters can be passed into this lookup; I(version_id) and I(version_stage)
+  - Optional parameters can be passed into this lookup; O(version_id) and O(version_stage).
   - Prior to release 6.0.0 this module was known as C(aws_ssm), the usage remains the same.
 
 options:
   _terms:
     description: Name of the secret to look up in AWS Secrets Manager.
-    required: True
+    required: true
   bypath:
     description: A boolean to indicate whether the parameter is provided as a hierarchy.
     default: false
-    type: boolean
+    type: bool
     version_added: 1.4.0
   nested:
     description: A boolean to indicate the secret contains nested values.
-    type: boolean
+    type: bool
     default: false
     version_added: 1.4.0
   version_id:
     description: Version of the secret(s).
-    required: False
+    required: false
   version_stage:
     description: Stage of the secret version.
-    required: False
+    required: false
   join:
     description:
       - Join two or more entries to form an extended secret.
       - This is useful for overcoming the 4096 character limit imposed by AWS.
-      - No effect when used with I(bypath).
-    type: boolean
+      - No effect when used with O(bypath).
+    type: bool
     default: false
   on_deleted:
     description:
       - Action to take if the secret has been marked for deletion.
-      - C(error) will raise a fatal error when the secret has been marked for deletion.
-      - C(skip) will silently ignore the deleted secret.
-      - C(warn) will skip over the deleted secret but issue a warning.
-    default: error
-    type: string
-    choices: ['error', 'skip', 'warn']
+      - V(error) will raise a fatal error when the secret has been marked for deletion.
+      - V(skip) will silently ignore the deleted secret.
+      - V(warn) will skip over the deleted secret but issue a warning.
+    default: "error"
+    type: str
+    choices: ["error", "skip", "warn"]
     version_added: 2.0.0
   on_missing:
     description:
       - Action to take if the secret is missing.
       - C(error) will raise a fatal error when the secret is missing.
       - C(skip) will silently ignore the missing secret.
       - C(warn) will skip over the missing secret but issue a warning.
-    default: error
-    type: string
-    choices: ['error', 'skip', 'warn']
+    default: "error"
+    type: str
+    choices: ["error", "skip", "warn"]
   on_denied:
     description:
       - Action to take if access to the secret is denied.
       - C(error) will raise a fatal error when access to the secret is denied.
       - C(skip) will silently ignore the denied secret.
       - C(warn) will skip over the denied secret but issue a warning.
-    default: error
-    type: string
-    choices: ['error', 'skip', 'warn']
+    default: "error"
+    type: str
+    choices: ["error", "skip", "warn"]
 extends_documentation_fragment:
   - amazon.aws.boto3
   - amazon.aws.common.plugins
   - amazon.aws.region.plugins
 """
 
 EXAMPLES = r"""
-- name: lookup secretsmanager secret in the current region
-  debug: msg="{{ lookup('amazon.aws.aws_secret', '/path/to/secrets', bypath=true) }}"
+- name: Lookup secretsmanager secret in the current region
+  ansible.builtin.debug: msg="{{ lookup('amazon.aws.aws_secret', '/path/to/secrets', bypath=true) }}"
 
 - name: Create RDS instance with aws_secret lookup for password param
-  rds:
-    command: create
-    instance_name: app-db
-    db_engine: MySQL
-    size: 10
+  amazon.aws.rds_instance:
+    state: present
+    db_instance_identifier: app-db
+    engine: mysql
     instance_type: db.m1.small
     username: dbadmin
     password: "{{ lookup('amazon.aws.aws_secret', 'DbSecret') }}"
     tags:
       Environment: staging
 
-- name: skip if secret does not exist
-  debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-not-exist', on_missing='skip')}}"
+- name: Skip if secret does not exist
+  ansible.builtin.debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-not-exist', on_missing='skip')}}"
 
-- name: warn if access to the secret is denied
-  debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-denied', on_denied='warn')}}"
+- name: Warn if access to the secret is denied
+  ansible.builtin.debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-denied', on_denied='warn')}}"
 
-- name: lookup secretsmanager secret in the current region using the nested feature
-  debug: msg="{{ lookup('amazon.aws.aws_secret', 'secrets.environments.production.password', nested=true) }}"
+- name: Lookup secretsmanager secret in the current region using the nested feature
+  ansible.builtin.debug: msg="{{ lookup('amazon.aws.aws_secret', 'secrets.environments.production.password', nested=true) }}"
   # The secret can be queried using the following syntax: `aws_secret_object_name.key1.key2.key3`.
   # If an object is of the form `{"key1":{"key2":{"key3":1}}}` the query would return the value `1`.
-- name: lookup secretsmanager secret in a specific region using specified region and aws profile using nested feature
-  debug: >
+- name: Lookup secretsmanager secret in a specific region using specified region and aws profile using nested feature
+  ansible.builtin.debug: >
    msg="{{ lookup('amazon.aws.aws_secret', 'secrets.environments.production.password', region=region, profile=aws_profile,
    access_key=aws_access_key, secret_key=aws_secret_key, nested=true) }}"
   # The secret can be queried using the following syntax: `aws_secret_object_name.key1.key2.key3`.
@@ -115,8 +114,7 @@
 
 RETURN = r"""
 _raw:
-  description:
-    Returns the value of the secret stored in AWS Secrets Manager.
+  description: Returns the value of the secret stored in AWS Secrets Manager.
 """
 
 import json