[Docs][2.10] Backportapalooza 11 (#71702)

* Add note on where inventory scripts moved to' (#71638)

(cherry picked from commit 2f240f5dd7)

* clarify that collection names use same requirements as namespaces (#71639)

(cherry picked from commit bbd4ec13f1)

* Fix typo in documentation (#71652)

Fix typo on the page about unit testing modules,

(cherry picked from commit 1ad0f666d5)

* Changed all_modules references to list_of_collections in the documentation (#71656)

(cherry picked from commit a34043c6be)

* Adds FAQ and other pointers for collections (#71606)

(cherry picked from commit b430f9b9aa)

* Docs(lineinfile): Update link to python regex docs (#71688)

There was a link still pointing at the python2 documentation.

(cherry picked from commit 11ba30183e)

* Docsite: add reference to Style guide (#71694)

(cherry picked from commit 73bed95ead)

Co-authored-by: Zois Pagoulatos <zpagoulatos@hotmail.com>
Co-authored-by: esmersmith <62951573+esmersmith@users.noreply.github.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Valentin Krasontovitsch <v.krasontov@gmail.com>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

docs/docsite/README.md

@@ -1,7 +1,7 @@
 Ansible documentation
 =====================
 
-This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/).
+This project hosts the source behind the general pages of [docs.ansible.com](https://docs.ansible.com/). Module-specific documentation is hosted in the various collections repositories. See [Ansible Galaxy](https://galaxy.ansible.com/), the list of [Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html), and the [ansible-collections organization](https://github.com/ansible-collections) for collections sources.
 
 To create clear, concise, and consistent contributions to Ansible documentation, please refer to the following information.
 
@@ -11,7 +11,7 @@ Contributions to the documentation are welcome.
 
 The Ansible community produces guidance on contributions, building documentation, and submitting pull requests, which you can find in [Contributing to the Ansible Documentation](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html).
 
-You can also join the [Docs Working Group](https://github.com/ansible/community/wiki/Docs).
+You can also join the [Docs Working Group](https://github.com/ansible/community/wiki/Docs) and/or the ``#ansible-docs`` channel on freenode IRC.
 
 Ansible style guide
 ===================
@@ -23,4 +23,4 @@ The Ansible community uses a range of tools and programs for working with Ansibl
 
 GitHub
 ======
-[Ansible documentation](https://github.com/ansible/ansible/tree/devel/docs/docsite) is hosted on the Ansible GitHub project. For GitHub workflows and other information, see the [GitHub Guides](https://guides.github.com/).
+[Ansible documentation](https://github.com/ansible/ansible/tree/devel/docs/docsite) is hosted on the Ansible GitHub project and various collection repositories, especially those in the [ansible-collections organization](https://github.com/ansible-collections). For general GitHub workflows and other information, see the [GitHub Guides](https://guides.github.com/).

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -268,7 +268,7 @@ To start a new collection:
 
 .. note::
 
-	Both the namespace and collection names have strict requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
+	Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
 
 Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
 

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -79,6 +79,8 @@ Module documentation should briefly and accurately define what each module and o
     * If an option is only sometimes required, describe the conditions. For example, "Required when I(state=present)."
     * If your module allows ``check_mode``, reflect this fact in the documentation.
 
+To create clear, concise, consistent, and useful documentation, follow the :ref:`style guide <style_guide>`.
+
 Each documentation field is described below. Before committing your module documentation, please test it at the command line and as HTML:
 
 * As long as your module file is :ref:`available locally <local_modules>`, you can use ``ansible-doc -t module my_module_name`` to view your module documentation at the command line. Any parsing errors will be obvious - you can view details by adding ``-vvv`` to the command.
@@ -96,7 +98,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
 :short_description:
 
-  * A short description which is displayed on the :ref:`all_modules` page and ``ansible-doc -l``.
+  * A short description which is displayed on the :ref:`list_of_collections` page and ``ansible-doc -l``.
   * The ``short_description`` is displayed by ``ansible-doc -l`` without any category grouping,
     so it needs enough detail to explain the module's purpose without the context of the directory structure in which it lives.
   * Unlike ``description:``, ``short_description`` should not have a trailing period/full stop.

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -479,8 +479,8 @@ For example vars plugins, see the source code for the `vars plugins included wit
 
 .. seealso::
 
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       List of all modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_api`
        Learn about the Python API for task execution
    :ref:`developing_inventory`

docs/docsite/rst/dev_guide/testing_units_modules.rst

@@ -15,8 +15,8 @@ Introduction
 
 This document explains why, how and when you should use unit tests for Ansible modules.
 The document doesn't apply to other parts of Ansible for which the recommendations are
-normally closer to the Python standard.  There is basic documentation for Ansible unit
+normally closer to the Python standard. There is basic documentation for Ansible unit
-tests in the developer guide :ref:`testing_units`.  This document should
+tests in the developer guide :ref:`testing_units`. This document should
 be readable for a new Ansible module author. If you find it incomplete or confusing,
 please open a bug or ask for help on Ansible IRC.
 
@@ -24,12 +24,12 @@ What Are Unit Tests?
 ====================
 
 Ansible includes a set of unit tests in the :file:`test/units` directory. These tests primarily cover the
-internals but can also can cover Ansible modules.  The structure of the unit tests matches
+internals but can also cover Ansible modules. The structure of the unit tests matches
 the structure of the code base, so the tests that reside in the :file:`test/units/modules/` directory
 are organized by module groups.
 
 Integration tests can be used for most modules, but there are situations where
-cases cannot be verified using integration tests.  This means that Ansible unit test cases
+cases cannot be verified using integration tests. This means that Ansible unit test cases
 may extend beyond testing only minimal units and in some cases will include some
 level of functional testing.
 
@@ -40,13 +40,13 @@ Why Use Unit Tests?
 Ansible unit tests have advantages and disadvantages. It is important to understand these.
 Advantages include:
 
-* Most unit tests are much faster than most Ansible integration tests.  The complete suite
+* Most unit tests are much faster than most Ansible integration tests. The complete suite
   of unit tests can be run regularly by a developer on their local system.
 * Unit tests can be run by developers who don't have access to the system which the module is
   designed to work on, allowing a level of verification that changes to core functions
   haven't broken module expectations.
 * Unit tests can easily substitute system functions allowing testing of software that
-  would be impractical.  For example, the ``sleep()`` function can be replaced and we check
+  would be impractical. For example, the ``sleep()`` function can be replaced and we check
   that a ten minute sleep was called without actually waiting ten minutes.
 * Unit tests are run on different Python versions. This allows us to
   ensure that the code behaves in the same way on different Python versions.
@@ -62,7 +62,7 @@ implementation
   problem between the internal code tested and the actual result delivered to the user
 
 Normally the Ansible integration tests (which are written in Ansible YAML) provide better
-testing for most module functionality.  If those tests already test a feature and perform
+testing for most module functionality. If those tests already test a feature and perform
 well there may be little point in providing a unit test covering the same area as well.
 
 When To Use Unit Tests
@@ -85,13 +85,13 @@ Providing quick feedback
 
 Example:
   A single step of the rds_instance test cases can take up to 20
-  minutes (the time to create an RDS instance in Amazon).  The entire
+  minutes (the time to create an RDS instance in Amazon). The entire
-  test run can last for well over an hour.  All 16 of the unit tests
+  test run can last for well over an hour. All 16 of the unit tests
   complete execution in less than 2 seconds.
 
 The time saving provided by being able to run the code in a unit test makes it worth
 creating a unit test when bug fixing a module, even if those tests do not often identify
-problems later.  As a basic goal, every module should have at least one unit test which
+problems later. As a basic goal, every module should have at least one unit test which
 will give quick feedback in easy cases without having to wait for the integration tests to
 complete.
 
@@ -110,9 +110,9 @@ Example:
 
 Another related use is in the situation where an API has versions which behave
 differently. A programmer working on a new version may change the module to work with the
-new API version and unintentionally break the old version.  A test case
+new API version and unintentionally break the old version. A test case
 which checks that the call happens properly for the old version can help avoid the
-problem.  In this situation it is very important to include version numbering in the test case
+problem. In this situation it is very important to include version numbering in the test case
 name (see `Naming unit tests`_ below).
 
 Providing specific design tests
@@ -134,9 +134,9 @@ of the code, such as installing all of the packages supplied as arguments to the
 How to unit test Ansible modules
 ================================
 
-There are a number of techniques for unit testing modules.  Beware that most
+There are a number of techniques for unit testing modules. Beware that most
 modules without unit tests are structured in a way that makes testing quite difficult and
-can lead to very complicated tests which need more work than the code.  Effectively using unit
+can lead to very complicated tests which need more work than the code. Effectively using unit
 tests may lead you to restructure your code. This is often a good thing and leads
 to better code overall. Good restructuring can make your code clearer and easier to understand.
 
@@ -158,7 +158,7 @@ Use of Mocks
 
 Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very
 useful in building unit tests for special / difficult cases, but they can also
-lead to complex and confusing coding situations.  One good use for mocks would be in
+lead to complex and confusing coding situations. One good use for mocks would be in
 simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use
 ``import units.compat.mock``).
 
@@ -203,7 +203,7 @@ API definition with unit test cases
 -----------------------------------
 
 API interaction is usually best tested with the function tests defined in Ansible's
-integration testing section, which run against the actual API.  There are several cases
+integration testing section, which run against the actual API. There are several cases
 where the unit tests are likely to work better.
 
 Defining a module against an API specification
@@ -214,7 +214,7 @@ an API that Ansible uses but which are beyond the control of the user.
 
 By writing a custom emulation of the calls that return data from the API, we can ensure
 that only the features which are clearly defined in the specification of the API are
-present in the message.  This means that we can check that we use the correct
+present in the message. This means that we can check that we use the correct
 parameters and nothing else.
 
 
@@ -522,7 +522,7 @@ Traps for maintaining Python 2 compatibility
 ============================================
 
 If you use the ``mock`` library from the Python 2.6 standard library, a number of the
-assert functions are missing but will return as if successful.  This means that test cases should take great care *not* use
+assert functions are missing but will return as if successful. This means that test cases should take great care *not* use
 functions marked as _new_ in the Python 3 documentation, since the tests will likely always
 succeed even if the code is broken when run on older versions of Python.
 

docs/docsite/rst/reference_appendices/common_return_values.rst

@@ -241,8 +241,8 @@ This key contains a list of dictionaries that will be presented to the user. Key
 
 .. seealso::
 
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       Learn about available modules
+       Browse existing collections, modules, and plugins
    `GitHub modules directory <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_
        Browse source of core and extras modules
    `Mailing List <https://groups.google.com/group/ansible-devel>`_

docs/docsite/rst/reference_appendices/faq.rst

@@ -5,6 +5,23 @@ Frequently Asked Questions
 
 Here are some commonly asked questions and their answers.
 
+.. _collections_transition:
+
+Where did all the modules go?
++++++++++++++++++++++++++++++
+
+In July, 2019, we announced that collections would be the `future of Ansible content delivery <https://www.ansible.com/blog/the-future-of-ansible-content-delivery>`_. A collection is a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. In Ansible 2.9 we added support for collections. In Ansible 2.10 we extracted most modules from the main ansible/ansible repository and placed them in :ref:`collections <list_of_collections>`. Collections may be maintained by the Ansible team, by the Ansible community, or by Ansible partners. The `ansible/ansible repository <https://github.com/ansible/ansible>`_ now contains the code for basic features and functions, such as copying module code to managed nodes. This code is also known as ``ansible-base``.
+
+* To learn more about using collections, see :ref:`collections`.
+* To learn more about developing collections, see :ref:`developing_collections`.
+* To learn more about contributing to existing collections, see the individual collection repository for guidelines, or see :ref:`contributing_maintained_collections` to contribute to one of the Ansible-maintained collections.
+
+.. _find_my_module:
+
+Where did this specific module go?
+++++++++++++++++++++++++++++++++++
+
+IF you are searching for a specific module, you can check the `runtime.yml <https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml>`_ file, which lists the first destination for each module that we extracted from the main ansible/ansible repository. Some modules have moved again since then. You can also search on `Ansible Galaxy <https://galaxy.ansible.com/>`_ or ask on one of our :ref:`IRC channels <communication_irc>`.
 
 .. _set_environment:
 

docs/docsite/rst/reference_appendices/test_strategies.rst

@@ -262,8 +262,8 @@ system.
 
 .. seealso::
 
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       All the documentation for Ansible modules
+       Browse existing collections, modules, and plugins
    :ref:`working_with_playbooks`
        An introduction to playbooks
    :ref:`playbooks_delegation`

docs/docsite/rst/scenario_guides/guide_aws.rst

@@ -269,8 +269,8 @@ documentation for a full list with examples.
 
 .. seealso::
 
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       All the documentation for Ansible modules
+       Browse existing collections, modules, and plugins
    :ref:`working_with_playbooks`
        An introduction to playbooks
    :ref:`playbooks_delegation`

docs/docsite/rst/user_guide/collections_using.rst

@@ -5,7 +5,7 @@
 Using collections
 *****************
 
-Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. As modules move from the core Ansible repository into collections, the module documentation will move to the `collections documentation page <https://docs.ansible.com/collections/>`_
+Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. As modules move from the core Ansible repository into collections, the module documentation will move to the :ref:`collections pages <list_of_collections>`.
 
 You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
 

docs/docsite/rst/user_guide/intro_adhoc.rst

@@ -196,8 +196,8 @@ Now that you understand the basic elements of Ansible execution, you are ready t
 
    :ref:`intro_configuration`
        All about the Ansible config file
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       A list of available modules
+       Browse existing collections, modules, and plugins
    :ref:`working_with_playbooks`
        Using Ansible for configuration management & deployment
    `Mailing List <https://groups.google.com/group/ansible-project>`_

docs/docsite/rst/user_guide/intro_dynamic_inventory.rst

@@ -197,7 +197,7 @@ Note that the OpenStack dynamic inventory script will cache results to avoid rep
 Other inventory scripts
 =======================
 
-You can find all included inventory scripts in the `contrib/inventory directory <https://github.com/ansible/ansible/tree/stable-2.9/contrib/inventory>`_. General usage is similar across all inventory scripts. You can also :ref:`write your own inventory script <developing_inventory>`.
+In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are now in the `community.general scripts/inventory directory <https://github.com/ansible-collections/community.general/tree/main/scripts/inventory>`_. We recommend you use :ref:`inventory_plugins` instead.
 
 .. _using_multiple_sources:
 

docs/docsite/rst/user_guide/playbooks_best_practices.rst

@@ -155,8 +155,8 @@ This pulls in variables from the group_vars/os_CentOS.yml file.
        Learn about YAML syntax
    :ref:`working_with_playbooks`
        Review the basic playbook features
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       Learn about available modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_modules`
        Learn how to extend Ansible by writing your own modules
    :ref:`intro_patterns`

docs/docsite/rst/user_guide/playbooks_intro.rst

@@ -139,8 +139,8 @@ The `ansible-lint default rules <https://docs.ansible.com/ansible-lint/rules/def
        Learn about YAML syntax
    :ref:`playbooks_best_practices`
        Tips for managing playbooks in the real world
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       Learn about available modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_modules`
        Learn to extend Ansible by writing your own modules
    :ref:`intro_patterns`

docs/docsite/rst/user_guide/playbooks_reuse_includes.rst

@@ -22,8 +22,8 @@ The content on this page has been moved to :ref:`playbooks_reuse`.
        Conditionals in playbooks
    :ref:`playbooks_loops`
        Loops in playbooks
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       Learn about available modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_modules`
        Learn how to extend Ansible by writing your own modules
    `GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_

docs/docsite/rst/user_guide/playbooks_reuse_roles.rst

@@ -466,8 +466,8 @@ Read the `Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_ page
        Loops in playbooks
    :ref:`tags`
        Using tags to select or skip roles/tasks in long playbooks
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       List of available modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_modules`
        Extending Ansible by writing your own modules
    `GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_

docs/docsite/rst/user_guide/sample_setup.rst

@@ -273,8 +273,8 @@ in the directory structure example at the start of this section.
        Learn about YAML syntax
    :ref:`working_with_playbooks`
        Review the basic playbook features
-   :ref:`all_modules`
+   :ref:`list_of_collections`
-       Learn about available modules
+       Browse existing collections, modules, and plugins
    :ref:`developing_modules`
        Learn how to extend Ansible by writing your own modules
    :ref:`intro_patterns`

lib/ansible/modules/lineinfile.py

@@ -40,7 +40,7 @@ options:
         settings.
       - When modifying a line the regexp should typically match both the initial state of
         the line as well as its state after replacement by C(line) to ensure idempotence.
-      - Uses Python regular expressions. See U(http://docs.python.org/2/library/re.html).
+      - Uses Python regular expressions. See U(https://docs.python.org/3/library/re.html).
     type: str
     aliases: [ regex ]
     version_added: '1.7'