[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

@@ -24,7 +24,7 @@ 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.
 

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'