4 28 docs backportapalooza (#77686)

* docs: Update porting guide for ansible 5.7.0 (#77646)

(cherry picked from commit 709ae7c050c8ad5aa0565b8d023303407f7ca9b6)

* remove import_play examples from include module (#77597)

(cherry picked from commit d321fa3f15cefa853d646985b2a201233cdb47c8)

* trim down to use sanity test docs requirements file (#77612)

* trim down to use sanity test docs requirements file
* add requirements back
Co-authored-by: Felix Fontein <felix@fontein.de>
* Update docs/docsite/rst/community/documentation_contributions.rst

(cherry picked from commit a65fbfad5b20b23b41c4f8cdd82161bb8c365953)

* Typo fix (#77648)

(cherry picked from commit cf5f0690f03aa7758a8e570478753b6dcbac79b6)

* Update guide_vultr.rst (#77665)

(cherry picked from commit f6fb402d1feab0c66e9eb107bdb37b8ae9c3ce4c)

* add select distro installs to docs (#77567)

(cherry picked from commit 096393a22132f97a15fee537981c596488b81540)

* community_steering_committee.rst: add new member (#77589)

(cherry picked from commit 3cbfee78525a5f7a6c6a32dc408d9feebccfcd6f)

* clarify latest release (#77577)

* clarify latest release
* fix tables

(cherry picked from commit f633b62cbc995befe47d98c735d57baacb9cda2e)

* typo in doc (#77672)

(cherry picked from commit c71faec59578fff019b1cd80e8ad3db24eea1aae)

Co-authored-by: David Moreau Simard <moi@dmsimard.com>
Co-authored-by: deosrc <deosrc@g-de.co.uk>
Co-authored-by: Jan-Piet Mens <jp@mens.de>
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

12 files changed, 168 insertions, 55 deletions

diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html
index 1ae0219b19..29ecc87b3c 100644
--- a/docs/docsite/.templates/banner.html
+++ b/docs/docsite/.templates/banner.html
@@ -46,7 +46,7 @@
         /* temp extra banner to advertise AnsibeFest2021 */
         banner += extra_banner;
 
-        msg += 'You are reading the latest community version of the Ansible documentation. Red Hat subscribers, select <b>2.9</b> in the version selection to the left for the most recent Red Hat release.';
+        msg += 'You are reading the <b>latest</b> (stable) community version of the Ansible documentation. Red Hat subscribers, select <b>2.9</b> in the version selection to the left for the most recent Red Hat release.';
       } else if (startsWith(current_url_path, "/ansible/2.9/")) {
         msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select <b>latest</b> from the version selector to the left for the most recent community version.';
       } else if (startsWith(current_url_path, "/ansible/devel/")) {
@@ -58,9 +58,9 @@
         msg += 'Please take our <a href="https://www.surveymonkey.co.uk/r/B9V3CDY">Docs survey</a> before December 31 to help us improve Ansible documentation.';
         */
 
-        msg += 'You are reading the <b>devel</b> version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest stable released version.';
+        msg += 'You are reading the <b>devel</b> version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the <b>latest</b> (stable) released version.';
       } else {
-        msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.';
+        msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the <b>latest</b> (stable) released version.';
       }
       msg += '</p>';
 
diff --git a/docs/docsite/known_good_reqs.txt b/docs/docsite/known_good_reqs.txt
deleted file mode 100644
index 52a3214101..0000000000
--- a/docs/docsite/known_good_reqs.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-# pip packages required to build docsite
-# tested Nov 11 2021
-# NOTE - this file must align with CI test for docs-build at
-#    test/sanity/code-smell/docs-build.requirements.txt
-#    test/sanity/code-smell/rstcheck.requirements.txt
-
-antsibull-docs == 1.0.0
-# sphinx 4.2.0 requires docutils < 0.18
-docutils == 0.17.1
-jinja2 == 3.0.3
-pygments == 2.10.0
-pyyaml == 6.0
-resolvelib == 0.5.4
-rstcheck == 3.3.1
-sphinx == 4.2.0
-sphinx-notfound-page == 0.8 # must be >= 0.6
-sphinx-intl == 2.0.1
-sphinx-ansible-theme === 0.9.1
-straight.plugin == 1.5.0 # Needed for hacking/build-ansible.py which is the backend build script
diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
index d91243314a..6d1ce4d3ec 100644
--- a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
+++ b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
@@ -108,8 +108,8 @@ Examine the output to see at which step the failure occurred. Investigate the re
 
 8. If the test succeeds, write more tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details.
 
-``community.postregesql`` example
-----------------------------------
+``community.postgresql`` example
+--------------------------------
 
 Here is a real example of writing integration tests from scratch for the ``community.postgresql.postgresql_info`` module.
 
diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst
index 8b3b0388ce..c2229d828f 100644
--- a/docs/docsite/rst/community/contributor_path.rst
+++ b/docs/docsite/rst/community/contributor_path.rst
@@ -51,7 +51,7 @@ You can learn these tools more in depth when working on your first contributions
 Each Ansible project has its own set of contributor guidelines. Familarize yourself with these as you prepare your first contributions.
 
 * :ref:`Ansible Core development <developer_guide>`.
-* :ref:`Ansible collectoin development <developing_collections>` and the collection-level contributor guidelines in the collection repository.
+* :ref:`Ansible collection development <developing_collections>` and the collection-level contributor guidelines in the collection repository.
 
 
 Making your first contribution
@@ -101,4 +101,4 @@ To reach the status, as the current Committee members did before getting it, alo
 
 * Subscribe to, comment on, and vote on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
 * Propose your topics.
-* If time permits, join the `Community meetings <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_  Note this is **NOT** a requirement.
\ No newline at end of file
+* If time permits, join the `Community meetings <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_  Note this is **NOT** a requirement.
diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst
index 12cc0d5811..51f30b7c3b 100644
--- a/docs/docsite/rst/community/documentation_contributions.rst
+++ b/docs/docsite/rst/community/documentation_contributions.rst
@@ -74,7 +74,7 @@ Setting up your environment to build documentation locally
 
 To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`.
 
-To work with documentation on your local machine, you need to have python-3.5 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two :file:`requirements.txt` files to make installation easier:
+To work with documentation on your local machine, you need to have python-3.9 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two files to make installation easier:
 
 .. _Ansible dependencies: https://github.com/ansible/ansible/blob/devel/requirements.txt
 .. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/docs/docsite/requirements.txt
@@ -84,12 +84,14 @@ To work with documentation on your local machine, you need to have python-3.5 or
     pip install --user -r requirements.txt
     pip install --user -r docs/docsite/requirements.txt
 
-The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`docs/docsite/known_good_reqs.txt` instead:
+The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI:
 
 .. code-block:: bash
 
     pip install --user -r requirements.txt
-    pip install --user -r docs/docsite/known_good_reqs.txt
+    pip install --user -r test/sanity/code-smell/docs-build.requirements.txt
+
+
 
 You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). 
 
diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst
index 2c933b0ea1..f21ad24e6c 100644
--- a/docs/docsite/rst/community/steering/community_steering_committee.rst
+++ b/docs/docsite/rst/community/steering/community_steering_committee.rst
@@ -35,6 +35,8 @@ The following table lists the current Steering Committee members. See :ref:`stee
   +------------------+---------------+-------------+
   | Name             | GitHub        | Start year  |
   +==================+===============+=============+
+  | Alexei Znamensky | russoz        | 2022        |
+  +------------------+---------------+-------------+
   | Alicia Cozine    | acozine       | 2021        |
   +------------------+---------------+-------------+
   | Andrew Klychkov  | Andersson007  | 2021        |
diff --git a/docs/docsite/rst/installation_guide/index.rst b/docs/docsite/rst/installation_guide/index.rst
index 8a7f41dbe3..332560e885 100644
--- a/docs/docsite/rst/installation_guide/index.rst
+++ b/docs/docsite/rst/installation_guide/index.rst
@@ -9,5 +9,6 @@ Welcome to the Ansible Installation Guide!
    :maxdepth: 2
 
    intro_installation
+   installation_distros
    intro_configuration
 
diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst
new file mode 100644
index 0000000000..ce07c6a70d
--- /dev/null
+++ b/docs/docsite/rst/installation_guide/installation_distros.rst
@@ -0,0 +1,110 @@
+.. _installing_distros:
+
+Installing Ansible on specific operating systems
+================================================
+
+The ``ansible`` package can always be :ref:`installed from PyPI using pip <intro_installation_guide>` on most systems but it is also packaged and maintained by the community for a variety of Linux distributions.
+
+The following instructions will guide you through installing the ``ansible`` package with your preferred distribution's package manager.
+
+.. contents::
+  :local:
+
+Installing Ansible on Fedora or CentOS 
+--------------------------------------
+
+On Fedora:
+
+.. code-block:: bash
+
+    $ sudo dnf install ansible
+
+On CentOS:
+
+.. code-block:: bash
+
+    $ sudo yum install epel-release
+    $ sudo yum install ansible
+
+RPMs for currently supported versions of CentOS are also available from `EPEL <https://fedoraproject.org/wiki/EPEL>`_.
+
+
+.. _from_apt:
+
+Installing Ansible on Ubuntu
+----------------------------
+
+Ubuntu builds are available `in a PPA here <https://launchpad.net/~ansible/+archive/ubuntu/ansible>`_.
+
+To configure the PPA on your system and install Ansible run these commands:
+
+.. code-block:: bash
+
+    $ sudo apt update
+    $ sudo apt install software-properties-common
+    $ sudo add-apt-repository --yes --update ppa:ansible/ansible
+    $ sudo apt install ansible
+
+.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` rather than ``apt`` in older versions. Also, be aware that only newer distributions (that is, 18.04, 18.10, and later) have a ``-u`` or ``--update`` flag. Adjust your script as needed.
+
+
+
+
+Installing Ansible on Debian
+----------------------------
+
+Debian users can use the same source as the Ubuntu PPA (using the following table).
+
+.. list-table::
+  :header-rows: 1
+
+  * - Debian
+    -
+    - Ubuntu
+  * - Debian 11 (Bullseye)
+    - ->
+    - Ubuntu 20.04 (Focal)
+  * - Debian 10 (Buster)
+    - ->
+    - Ubuntu 18.04 (Bionic)
+
+
+.. note::
+
+    Ansible releases are only built for Ubuntu 18.04 (Bionic) or later releases.
+
+Add the following line to ``/etc/apt/sources.list`` or ``/etc/apt/sources.list.d/ansible.list``:
+
+.. code-block:: bash
+
+    deb http://ppa.launchpad.net/ansible/ansible/ubuntu MATCHING_UBUNTU_CODENAME_HERE main
+
+Example for Debian 11 (Bullseye)
+
+.. code-block:: bash
+
+    deb http://ppa.launchpad.net/ansible/ansible/ubuntu focal main
+
+Then run these commands:
+
+.. code-block:: bash
+
+    $ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 93C4A3FD7BB9C367
+    $ sudo apt update
+    $ sudo apt install ansible
+
+
+
+.. _from_windows:
+
+Installing Ansible on Windows
+------------------------------
+
+You cannot use a Windows system for the Ansible control node. See :ref:`windows_faq_ansible`
+
+.. seealso::
+
+    `Installing Ansible on ARch Linux <https://wiki.archlinux.org/title/Ansible#Installation>`_
+       Distro-specific installation on Arch Linux
+    `Installing Ansible on Clear Linux <https://clearlinux.org/software/bundle/ansible>`_
+       Distro-specific installation on Clear Linux
diff --git a/docs/docsite/rst/porting_guides/porting_guide_5.rst b/docs/docsite/rst/porting_guides/porting_guide_5.rst
index c788d58a76..e005c97c04 100644
--- a/docs/docsite/rst/porting_guides/porting_guide_5.rst
+++ b/docs/docsite/rst/porting_guides/porting_guide_5.rst
@@ -127,6 +127,31 @@ Networking
 
 No notable changes
 
+Porting Guide for v5.7.0
+========================
+
+Major Changes
+-------------
+
+community.postgresql
+~~~~~~~~~~~~~~~~~~~~
+
+- postgresql_user - the ``priv`` argument has been deprecated and will be removed in ``community.postgresql 3.0.0``. Please use the ``postgresql_privs`` module to grant/revoke privileges instead (https://github.com/ansible-collections/community.postgresql/issues/212).
+
+fortinet.fortios
+~~~~~~~~~~~~~~~~
+
+- Support FortiOS 7.0.2, 7.0.3, 7.0.4, 7.0.5.
+
+Deprecated Features
+-------------------
+
+community.general
+~~~~~~~~~~~~~~~~~
+
+- nmcli - deprecate default hairpin mode for a bridge. This so we can change it to ``false`` in community.general 7.0.0, as this is also the default in ``nmcli`` (https://github.com/ansible-collections/community.general/pull/4334).
+- proxmox inventory plugin - the current default ``true`` of the ``want_proxmox_nodes_ansible_host`` option has been deprecated. The default will change to ``false`` in community.general 6.0.0. To keep the current behavior, explicitly set ``want_proxmox_nodes_ansible_host`` to ``true`` in your inventory configuration. We suggest to already switch to the new behavior by explicitly setting it to ``false``, and by using ``compose:`` to set ``ansible_host`` to the correct value. See the examples in the plugin documentation for details (https://github.com/ansible-collections/community.general/pull/4466).
+
 Porting Guide for v5.6.0
 ========================
 
diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
index 672f6b7a23..f1cd464a28 100644
--- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
+++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
@@ -71,15 +71,15 @@ Ansible community changelogs
 
 This table links to the changelogs for each major Ansible release. These changelogs contain the dates and significant changes in each minor release.
 
-==================================      =================================================
-Ansible Community Package Release       Status
-==================================      =================================================
-6.0.0                                   In development (unreleased)
-`5.x Changelogs`_                       Current
-`4.x Changelogs`_                       End of life after 4.10
-`3.x Changelogs`_                       Unmaintained (end of life)
-`2.10 Changelogs`_                      Unmaintained (end of life)
-==================================      =================================================
+==================================      ============================    =========================
+Ansible Community Package Release       Status                          Core version dependency
+==================================      ============================    =========================
+6.0.0                                   In development (unreleased)     2.13
+`5.x Changelogs`_                       Current (latest stable)         2.12
+`4.x Changelogs`_                       End of life after 4.10          2.11
+`3.x Changelogs`_                       Unmaintained (end of life)      2.10
+`2.10 Changelogs`_                      Unmaintained (end of life)      2.10
+==================================      ============================    =========================
 
 .. _5.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst
 .. _4.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/4/CHANGELOG-v4.rst
diff --git a/docs/docsite/rst/scenario_guides/guide_vultr.rst b/docs/docsite/rst/scenario_guides/guide_vultr.rst
index c5d5adeca7..a946c91dc2 100644
--- a/docs/docsite/rst/scenario_guides/guide_vultr.rst
+++ b/docs/docsite/rst/scenario_guides/guide_vultr.rst
@@ -44,8 +44,8 @@ If ``VULTR_API_ACCOUNT`` environment variable or ``api_account`` module paramete
 Authentication
 --------------
 
-Before using the Ansible modules to interact with Vultr, ones need an API key.
-If one doesn't own one yet, log in to `Vultr <https://www.vultr.com>`_ go to Account, then API, enable API then the API key should show up.
+Before using the Ansible modules to interact with Vultr, you need an API key.
+If you don't yet own one, log in to `Vultr <https://www.vultr.com>`_ go to Account, then API, enable API then the API key should show up.
 
 Ensure you allow the usage of the API key from the proper IP addresses.
 
@@ -73,7 +73,7 @@ To check that everything is working properly run the following command:
   }
 
 
-If a similar output displays then everything is setup properly, else please ensure the proper ``VULTR_API_KEY`` has been specified and that Access Control on Vultr > Account > API page are accurate.
+If a similar output displays then everything is setup properly, else please ensure the proper ``VULTR_API_KEY`` has been specified and that Access Controls on Vultr > Account > API page are accurate.
 
 
 Usage
@@ -100,7 +100,7 @@ Dynamic Inventory
 -----------------
 
 Ansible provides a dynamic inventory plugin for `Vultr <https://www.vultr.com>`_.
-The configuration process is exactly the same as the one for the modules.
+The configuration process is exactly the same as for the modules.
 
 To be able to use it you need to enable it first by specifying the following in the ``ansible.cfg`` file:
 
diff --git a/lib/ansible/modules/_include.py b/lib/ansible/modules/_include.py
index db4445a9df..60deb9476c 100644
--- a/lib/ansible/modules/_include.py
+++ b/lib/ansible/modules/_include.py
@@ -11,10 +11,10 @@ DOCUMENTATION = r'''
 ---
 author: Ansible Core Team (@ansible)
 module: include
-short_description: Include a play or task list
+short_description: Include a task list
 description:
-  - Includes a file with a list of plays or tasks to be executed in the current playbook.
-  - Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks
+  - Includes a file with a list of tasks to be executed in the current playbook.
+  - Lists of tasks can only be included where tasks
     normally run (in play).
   - Before Ansible 2.0, all includes were 'static' and were executed when the play was compiled.
   - Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each
@@ -40,7 +40,7 @@ notes:
     in an effort to clarify behaviours we are moving to a new set modules (M(ansible.builtin.include_tasks),
     M(ansible.builtin.include_role), M(ansible.builtin.import_playbook), M(ansible.builtin.import_tasks))
     that have well established and clear behaviours.
-  - B(This module will still be supported for some time but we are looking at deprecating it in the near future.)
+  - This module no longer supporst including plays. Use M(ansible.builtin.import_playbook) instead.
 seealso:
 - module: ansible.builtin.import_playbook
 - module: ansible.builtin.import_role
@@ -52,14 +52,6 @@ seealso:
 '''
 
 EXAMPLES = r'''
-- hosts: localhost
-  tasks:
-    - ansible.builtin.debug:
-        msg: play1
-
-- name: Include a play after another play
-  ansible.builtin.include: otherplays.yaml
-
 
 - hosts: all
   tasks:
@@ -84,5 +76,5 @@ EXAMPLES = r'''
 '''
 
 RETURN = r'''
-# This module does not return anything except plays or tasks to execute.
+# This module does not return anything except tasks to execute.
 '''