Move docs fragments about

ansible-collections · Nov 5, 2022 · c241c38 · c241c38
1 parent 25e8e35
commit c241c38
Show file tree

Hide file tree

Showing 8 changed files with 369 additions and 192 deletions.
diff --git a/docs/docsite/rst/dev_guidelines.rst b/docs/docsite/rst/dev_guidelines.rst
@@ -297,8 +297,8 @@ Common Documentation Fragments for Connection Parameters
 There are four :ref:`common documentation fragments <module_docs_fragments>`
 that should be included into almost all AWS modules:
 
-* ``aws`` - contains the common boto3 connection parameters
-* ``ec2`` - contains the common region parameter required for many AWS modules
+* ``common.modules`` - contains the common boto3 connection parameters
+* ``region.modules`` - contains the common region parameter required for many AWS modules
 * ``boto3`` - contains the minimum requirements for the collection
 * ``tags`` - contains the common tagging parameters used by many AWS modules
 
@@ -311,8 +311,30 @@ and that the more esoteric connection options are documented. For example:
    module: my_module
    # some lines omitted here
    extends_documentation_fragment:
-       - amazon.aws.aws
-       - amazon.aws.ec2
+       - amazon.aws.common.modules
+       - amazon.aws.region.modules
+       - amazon.aws.boto3
+   '''
+
+Other plugin types have a slightly different document fragment format, and should use
+the following fragments:
+
+* ``common.plugins`` - contains the common boto3 connection parameters
+* ``region.plugins`` - contains the common region parameter required for many AWS modules
+* ``boto3`` - contains the minimum requirements for the collection
+* ``tags`` - contains the common tagging parameters used by many AWS modules
+
+These fragments should be used rather than re-documenting these properties to ensure consistency
+and that the more esoteric connection options are documented. For example:
+
+.. code-block:: python
+
+   DOCUMENTATION = '''
+   module: my_module
+   # some lines omitted here
+   extends_documentation_fragment:
+       - amazon.aws.common.modules
+       - amazon.aws.region.modules
        - amazon.aws.boto3
    '''
 

diff --git a/plugins/doc_fragments/aws.py b/plugins/doc_fragments/aws.py
@@ -1,133 +1,15 @@
 # -*- coding: utf-8 -*-
-
-# Copyright: (c) 2014, Will Thames <[email protected]>
+# (c) 2022 Red Hat Inc.
+#
+# This file is part of Ansible
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+import ansible_collections.amazon.aws.plugins.doc_fragments.common as common_fragments
 
-class ModuleDocFragment(object):
 
-    # AWS only documentation fragment
-    DOCUMENTATION = r'''
-options:
-  access_key:
-    description:
-      - AWS access key ID.
-      - See the AWS documentation for more information about access tokens
-        U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
-      - The C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY)
-        environment variables may also be used in decreasing order of
-        preference.
-      - The I(aws_access_key) and I(profile) options are mutually exclusive.
-      - The I(aws_access_key_id) alias was added in release 5.1.0 for
-        consistency with the AWS botocore SDK.
-      - The I(ec2_access_key) alias has been deprecated and will be removed in a
-        release after 2024-12-01.
-      - Support for the C(EC2_ACCESS_KEY) environment variable has been
-        deprecated and will be removed in a release after 2024-12-01.
-    type: str
-    aliases: ['aws_access_key_id', 'aws_access_key', 'ec2_access_key']
-  secret_key:
-    description:
-      - AWS secret access key.
-      - See the AWS documentation for more information about access tokens
-        U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
-      - The C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY)
-        environment variables may also be used in decreasing order of
-        preference.
-      - The I(secret_key) and I(profile) options are mutually exclusive.
-      - The I(aws_secret_access_key) alias was added in release 5.1.0 for
-        consistency with the AWS botocore SDK.
-      - The I(ec2_secret_key) alias has been deprecated and will be removed in a
-        release after 2024-12-01.
-      - Support for the C(EC2_SECRET_KEY) environment variable has been
-        deprecated and will be removed in a release after 2024-12-01.
-    type: str
-    aliases: ['aws_secret_access_key', 'aws_secret_key', 'ec2_secret_key']
-  session_token:
-    description:
-      - AWS STS session token for use with temporary credentials.
-      - See the AWS documentation for more information about access tokens
-        U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
-      - The C(AWS_SESSION_TOKEN), C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN)
-        environment variables may also be used in decreasing order of preference.
-      - The I(security_token) and I(profile) options are mutually exclusive.
-      - Aliases I(aws_session_token) and I(session_token) were added in release
-        3.2.0, with the parameter being renamed from I(security_token) to
-        I(session_token) in release 6.0.0.
-      - The I(security_token), I(aws_security_token), and I(access_token)
-        aliases have been deprecated and will be removed in a release after
-        2024-12-01.
-      - Support for the C(EC2_SECRET_KEY) and C(AWS_SECURITY_TOKEN) environment
-        variables has been deprecated and will be removed in a release after
-        2024-12-01.
-    type: str
-    aliases: ['aws_session_token', 'security_token', 'aws_security_token', 'access_token']
-  profile:
-    description:
-      - A named AWS profile to use for authentication.
-      - See the AWS documentation for more information about named profiles
-        U(https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
-      - The C(AWS_PROFILE) environment variable may also be used.
-      - The I(profile) option is mutually exclusive with the I(aws_access_key),
-        I(aws_secret_key) and I(security_token) options.
-    type: str
-    aliases: ['aws_profile']
+class ModuleDocFragment(object):
 
-  endpoint_url:
-    description:
-      - URL to connect to instead of the default AWS endpoints.  While this
-        can be used to connection to other AWS-compatible services the
-        amazon.aws and community.aws collections are only tested against
-        AWS.
-      - The  C(AWS_URL) or C(EC2_URL) environment variables may also be used,
-        in decreasing order of preference.
-      - The I(ec2_url) and I(s3_url) aliases have been deprecated and will be
-        removed in a release after 2024-12-01.
-      - Support for the C(EC2_URL) environment variable has been deprecated and
-        will be removed in a release after 2024-12-01.
-    type: str
-    aliases: ['ec2_url', 'aws_endpoint_url', 's3_url' ]
-  aws_ca_bundle:
-    description:
-      - The location of a CA Bundle to use when validating SSL certificates.
-      - The C(AWS_CA_BUNDLE) environment variable may also be used.
-    type: path
-  validate_certs:
-    description:
-      - When set to C(false), SSL certificates will not be validated for
-        communication with the AWS APIs.
-      - Setting I(validate_certs=false) is strongly discouraged, as an
-        alternative, consider setting I(aws_ca_bundle) instead.
-    type: bool
-    default: true
-  aws_config:
-    description:
-      - A dictionary to modify the botocore configuration.
-      - Parameters can be found in the AWS documentation
-        U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config).
-    type: dict
-  debug_botocore_endpoint_logs:
-    description:
-      - Use a C(botocore.endpoint) logger to parse the unique (rather than total)
-        C("resource:action") API calls made during a task, outputing the set to
-        the resource_actions key in the task results. Use the
-        C(aws_resource_action) callback to output to total list made during
-        a playbook.
-      - The C(ANSIBLE_DEBUG_BOTOCORE_LOGS) environment variable may also be used.
-    type: bool
-    default: false
-notes:
-  - B(Caution:) For modules, environment variables and configuration files are
-    read from the Ansible 'host' context and not the 'controller' context.
-    As such, files may need to be explicitly copied to the 'host'.  For lookup
-    and connection plugins, environment variables and configuration files are
-    read from the Ansible 'controller' context and not the 'host' context.
-  - The AWS SDK (boto3) that Ansible uses may also read defaults for credentials
-    and other settings, such as the region, from its configuration files in the
-    Ansible 'host' context (typically C(~/.aws/credentials)).
-    See U(https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)
-    for more information.
-'''
+    DOCUMENTATION = common_fragments.ModuleDocFragment.MODULES
diff --git a/plugins/doc_fragments/aws_region.py b/plugins/doc_fragments/aws_region.py
@@ -1,21 +1,16 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2017,  Ansible Project
+# (c) 2022 Red Hat Inc.
+#
+# This file is part of Ansible
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+import ansible_collections.amazon.aws.plugins.doc_fragments.region as region_fragments
+
 
 class ModuleDocFragment(object):
 
-    # Plugin option for AWS region
-    DOCUMENTATION = r'''
-options:
-  region:
-    description: The region for which to create the connection.
-    type: str
-    env:
-      - name: EC2_REGION
-      - name: AWS_REGION
-'''
+    DOCUMENTATION = region_fragments.ModuleDocFragment.PLUGINS
diff --git a/plugins/doc_fragments/boto3.py b/plugins/doc_fragments/boto3.py
@@ -1,19 +1,25 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2022,  Ansible Project
+# Copyright: (c) 2022, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+from ansible_collections.amazon.aws.plugins.module_utils import botocore as botocore_utils
+
 
 class ModuleDocFragment(object):
 
     # Minimum requirements for the collection
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options: {}
 requirements:
   - python >= 3.6
-  - boto3 >= 1.18.0
-  - botocore >= 1.21.0
-'''
+  - boto3 >= {0}
+  - botocore >= {1}
+""".format(botocore_utils.MINIMUM_BOTOCORE_VERSION, botocore_utils.MINIMUM_BOTO3_VERSION)
+
+    # Modules and Plugins can (currently) use the same fragment
+    MODULES = DOCUMENTATION
+    PLUGINS = DOCUMENTATION