Backportapalooza5 (#74706)

* Jinja intersphinx should point at 3.0; other updates

(cherry picked from commit 8c34eaa69f)

* Update AWS guides with new SDK and Python requirements (#74585)

The 2.0 collection releases will introduce new Python requirements
and a new SDK support policy

(cherry picked from commit fa15d35cb1)

* Add JC filter plugin example (#74563)

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 91212b2008)

* Fix typo on roles documentation (#74696)

##### SUMMARY
Small fix on the roles directory structure documentation

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

(cherry picked from commit 25de07946c)

* intro: Add a note about current user (#74638)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 39df263f1a)

Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Jill R <4121322+jillr@users.noreply.github.com>
Co-authored-by: Kelly Brazil <kellyjonbrazil@gmail.com>
Co-authored-by: m0nt3cr1st0 <gonzalo.rubio.casas@gmail.com>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>

docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst

@@ -9,6 +9,47 @@ The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws
 .. contents::
    :local:
 
+Requirements
+============
+
+Python Compatibility
+--------------------
+
+AWS content in Ansible 2.9 and 1.x collection releases supported Python 2.7 and newer.
+
+Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_.  Contributions to both collections that target the 2.0 or later collection releases can be written to support Python 3.6+ syntax.
+
+SDK Version Support
+-------------------
+
+Starting with the 2.0 releases of both collections, it is generally the policy to support the versions of botocore and boto3 that were released 12 months prior to the most recent major collection release, following semantic versioning (for example, 2.0.0, 3.0.0).
+
+Features and functionality that require newer versions of the SDK can be contributed provided they are noted in the module documentation:
+
+.. code-block:: yaml
+
+  DOCUMENTATION = '''
+  ---
+  module: ec2_vol
+  options:
+    throughput:
+      description:
+        - Volume throughput in MB/s.
+        - This parameter is only valid for gp3 volumes.
+        - Valid range is from 125 to 1000.
+        - Requires at least botocore version 1.19.27.
+      type: int
+      version_added: 1.4.0
+
+And handled using the ``botocore_at_least`` helper method:
+
+.. code-block:: python
+
+    if module.params.get('throughput'):
+        if not module.botocore_at_least("1.19.27"):
+            module.fail_json(msg="botocore >= 1.19.27 is required to set the throughput for a volume")
+
+
 Maintaining existing modules
 ============================
 
@@ -154,7 +195,7 @@ Supporting Module Defaults
 
 The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common
 authentication parameters.  To do the same for your new module, add an entry for it in
-``lib/ansible/config/module_defaults.yml``.  These entries take the form of:
+``meta/runtime.yml``.  These entries take the form of:
 
 .. code-block:: yaml
 

docs/docsite/rst/network/user_guide/cli_parsing.rst

@@ -56,6 +56,8 @@ The ``cli_parse`` module includes the following cli_parsing plugins:
   A library for semi-structured text parsing using templates, with added capabilities to simplify the process
 ``pyats``
   Uses the parsers included with the Cisco Test Automation & Validation Solution
+``jc``
+  A python module that converts the output of dozens of popular Linux/UNIX/macOS/Windows commands and file types to python dictionaries or lists of dictionaries. Note: this filter plugin can be found in the ``community.general`` collection.
 ``json``
   Converts JSON output at the CLI to an Ansible native data structure
 
@@ -583,6 +585,29 @@ The task sets the follow fact as the ``interfaces`` fact for the host:
      state: up
 
 
+Parsing with JC
+-----------------
+
+JC is a python library that converts the output of dozens of common Linux/UNIX/macOS/Windows command-line tools and file types to python dictionaries or lists of dictionaries for easier parsing. JC is available as a filter plugin in the ``community.general`` collection.
+
+The following is an example using JC to parse the output of the ``dig`` command:
+
+.. code-block:: yaml
+
+   - name: "Run dig command and parse with jc"
+     hosts: ubuntu
+     tasks:
+     - shell: dig example.com
+       register: result
+     - set_fact:
+         myvar: "{{ result.stdout | community.general.jc('dig') }}"
+     - debug:
+         msg: "The IP is: {{ myvar[0].answer[0].data }}"
+
+- The JC project and documentation can be found `here <https://github.com/kellyjonbrazil/jc/>`_.
+- See this `blog entry <https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansible-with-jc/>`_ for more information.
+
+
 Converting XML
 -----------------
 

docs/docsite/rst/scenario_guides/guide_aws.rst

@@ -11,7 +11,10 @@ section is to explain how to put Ansible modules together (and use inventory scr
 
 Requirements for the AWS modules are minimal.
 
-All of the modules require and are tested against recent versions of boto, usually boto3. Check the module documentation for the minimum required version for each module. You must have the boto3 Python module installed on your control machine. You may also need the original boto package. You can install these modules from your OS distribution or using the python package installer: ``pip install boto3``.
+All of the modules require and are tested against recent versions of botocore and boto3.  Starting with the 2.0 AWS collection releases, it is generally the policy of the collections to support the versions of these libraries released 12 months prior to the most recent major collection revision. Individual modules may require a more recent library version to support specific features or may require the boto library, check the module documentation for the minimum required version for each module. You must have the boto3 Python module installed on your control machine. You can install these modules from your OS distribution or using the python package installer: ``pip install boto3``.
+
+Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_ and Python 3.6 or greater will be required.
+
 
 Whereas classically Ansible will execute tasks in its host loop against multiple remote machines, most cloud-control steps occur on your local machine with reference to the regions to control.
 

docs/docsite/rst/user_guide/intro_getting_started.rst

@@ -81,6 +81,8 @@ You should see output for each host in your inventory, similar to this:
        "ping": "pong"
    }
 
+You can use ``-u`` as one way to specify the user to connect as, by default Ansible uses SSH, which defaults to the 'current user'.
+
 Now run a live command on all of your nodes:
 
 .. code-block:: bash

docs/docsite/rst/user_guide/playbooks_reuse_roles.rst

@@ -12,7 +12,7 @@ Roles let you automatically load related vars, files, tasks, handlers, and other
 Role directory structure
 ========================
 
-An Ansible role has a defined directory structure with seven main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example:
+An Ansible role has a defined directory structure with eight main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example:
 
 .. code-block:: text