[Backport][Docs] Docs 2.12 backportapalooza7 (#76298)

* Stop using "checksumming" instead of "encrypting" in the docs (#76168)

* Hashing is not encrypting

All encryption systems have a formal inverse function to decrypt
A hash is a one way function without inverse by definition

* Update docs/docsite/rst/user_guide/playbooks_filters.rst

Co-authored-by: Sandra McCann <samccann@redhat.com>

* ansible-core 2.12 dropped support for galaxy.yaml. (#76179)

* apt - remove obsolete documentation (#76243)

The lock_timeout feature was recently added to the apt module making
this section in the documentation no longer necessary

* Documentation for other types in collection `requirements.yml` (#75872)

* Docs: Link to valid data types for role parameters (#76276)

* Fixed typo in keyword_desc.yml (#76280)

The description of 'max_fail_percentage' had a typo.

* Restore documentation on M() and R() (#76284)

* Undo most of bf99442, add note on where R() does not work.
Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

Co-authored-by: Vicente Jimenez Aguilar <googuy@gmail.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Sam Doran <sdoran@redhat.com>
Co-authored-by: Daniel Goldman <merkavabuilder@gmail.com>
Co-authored-by: nkoechling <nkoechling@users.noreply.github.com>

docs/docsite/rst/dev_guide/developing_collections_distributing.rst

@@ -54,7 +54,7 @@ You can create additional namespaces on Ansible Galaxy if you choose. For Red Ha
 * To create a namespace on Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
 * To create a namespace on Red Hat Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
 
-Specify the namespace in the :file:`galaxy.yaml` file for each collection. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`.
+Specify the namespace in the :file:`galaxy.yml` file for each collection. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
 
 .. _galaxy_get_token:
 
@@ -124,7 +124,7 @@ Building your collection tarball
 
 After configuring one or more distribution servers, build a collection tarball. The collection tarball is the published artifact, the object that you upload and other users download to install your collection. To build a collection tarball:
 
-#. Review the version number in your :file:`galaxy.yaml` file. Each time you publish your collection, it must have a new version number. You cannot make changes to existing versions of your collection on a distribution server. If you try to upload the same collection version more than once, the distribution server returns the error ``Code: conflict.collection_exists``. Collections follow semantic versioning rules. For more information on versions, see :ref:`collection_versions`. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`.
+#. Review the version number in your :file:`galaxy.yml` file. Each time you publish your collection, it must have a new version number. You cannot make changes to existing versions of your collection on a distribution server. If you try to upload the same collection version more than once, the distribution server returns the error ``Code: conflict.collection_exists``. Collections follow semantic versioning rules. For more information on versions, see :ref:`collection_versions`. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
 #. Run ``ansible-galaxy collection build`` from inside the top-level directory of the collection. For example:
 
 .. code-block:: bash

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -244,6 +244,8 @@ You can link from your module documentation to other module docs, other resource
 
 * ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
 * ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
+* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``.  Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
+* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
 
 There are also some macros which do not create links but we use them to display certain types of
 content in a uniform way:
@@ -256,12 +258,17 @@ content in a uniform way:
 
 .. note::
 
-  For links between modules and documentation within a collection, you can use either of the options above. Use ``U()`` or ``L()`` with full URLs (not relative links).
+  Cross-references with ``R()`` currently **do not work** inside option and return value documentations. They do work however in the global description, notes, and ``seealso`` descriptions.
 
 .. note::
-    - When a collection is not the right granularity, use ``C(..)``:
 
-        - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
+  For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links.
+
+.. note::
+  To refer to a group of modules in a collection, use ``R()``.  When a collection is not the right granularity, use ``C(..)``:
+
+    - ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
+    - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
 
 .. note::
 

docs/docsite/rst/galaxy/user_guide.rst

@@ -83,6 +83,11 @@ Downloading a collection for offline use
 
 .. include:: ../shared_snippets/download_tarball_collections.txt
 
+Installing a collection from source files
+-----------------------------------------
+
+.. include:: ../shared_snippets/installing_collections_file.rst
+
 Installing a collection from a git repository
 ---------------------------------------------
 

docs/docsite/rst/shared_snippets/installing_collections_file.rst

@@ -0,0 +1,24 @@
+Ansible can also install from a source directory in several ways:
+
+.. code-block:: yaml
+
+    collections:
+      # directory containing the collection
+      - source: ./my_namespace/my_collection/
+        type: dir
+
+      # directory containing a namespace, with collections as subdirectories
+      - source: ./my_namespace/
+        type: subdirs
+
+Ansible can also install a collection collected with ``ansible-galaxy collection build`` or downloaded from Galaxy for offline use by specifying the output file directly:
+
+.. code-block:: yaml
+
+    collections:
+      - source: /tmp/my_namespace-my_collection-1.0.0.tar.gz
+        type: file
+
+.. note::
+
+    Relative paths are calculated from the current working directory (where you are invoking ``ansible-galaxy install -r`` from). They are not taken relative to the ``requirements.yml`` file.

docs/docsite/rst/shared_snippets/installing_multiple_collections.txt

@@ -22,7 +22,7 @@ You can specify four keys for each collection entry:
 
 The ``version`` key uses the same range identifier format documented in :ref:`collections_older_version`. 
 
-The ``type`` key can be set to ``galaxy``, ``url``, ``file``, and ``git``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection.
+The ``type`` key can be set to ``file``, ``galaxy``, ``git``, ``url``, ``dir``, or ``subdirs``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection.
 
 When you install a collection with ``type: git``, the ``version`` key can refer to a branch or to a `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ object (commit or tag). For example:
 

docs/docsite/rst/user_guide/collections_using.rst

@@ -37,11 +37,6 @@ Installing an older version of a collection
 
 .. include:: ../shared_snippets/installing_older_collection.txt
 
-Installing a collection from a git repository
----------------------------------------------
-
-.. include:: ../shared_snippets/installing_collections_git_repo.txt
-
 .. _collection_requirements_file:
 
 Install multiple collections with a requirements file
@@ -56,6 +51,15 @@ Downloading a collection for offline use
 
 .. include:: ../shared_snippets/download_tarball_collections.txt
 
+Installing a collection from source files
+-----------------------------------------
+
+.. include:: ../shared_snippets/installing_collections_file.rst
+
+Installing a collection from a git repository
+---------------------------------------------
+
+.. include:: ../shared_snippets/installing_collections_git_repo.txt
 
 .. _galaxy_server_config:
 

docs/docsite/rst/user_guide/playbooks_filters.rst

@@ -1294,8 +1294,8 @@ This allows for dynamic generation of VLAN lists on a Cisco IOS tagged interface
 
 .. _hash_filters:
 
-Encrypting and checksumming strings and passwords
-=================================================
+Hashing and encrypting strings and passwords
+==============================================
 
 .. versionadded:: 1.9
 

docs/docsite/rst/user_guide/playbooks_reuse_roles.rst

@@ -320,7 +320,7 @@ role ``meta/argument_specs.yml`` file. All fields are lower-case.
 
         :type:
 
-           * The data type of the option. Default is ``str``.
+           * The data type of the option. See :ref:`Argument spec <argument_spec>` for allowed values for ``type``. Default is ``str``.
            * If an option is of type ``list``, ``elements`` should be specified.
 
         :required:

lib/ansible/keyword_desc.yml

@@ -41,7 +41,7 @@ ignore_errors: Boolean that allows you to ignore task failures and continue with
 ignore_unreachable: Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see :term:`ignore_errors`) but is useful for groups of volatile/ephemeral hosts.
 loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)"
 loop_control: Several keys here allow you to modify/set loop behaviour in a task. See :ref:`loop_control`.
-max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only wokrs on linear or linear derived strategies.
+max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only works on linear or linear derived strategies.
 module_defaults: Specifies default parameter values for modules.
 name: "Identifier. Can be used for documentation, or in tasks/handlers."
 no_log: Boolean that controls information disclosure.

lib/ansible/modules/apt.py

@@ -170,7 +170,7 @@
     version_added: "2.4"
   lock_timeout:
     description:
-      - How many seconds will this action wait to aquire a lock on the apt db.
+      - How many seconds will this action wait to acquire a lock on the apt db.
       - Sometimes there is a transitory lock and this will retry at least until timeout is hit.
     type: int
     default: 60
@@ -298,18 +298,6 @@
 - name: Remove dependencies that are no longer required
   apt:
     autoremove: yes
-
-# Sometimes apt tasks fail because apt is locked by an autoupdate or by a race condition on a thread.
-# To check for a lock file before executing, and keep trying until the lock file is released:
-- name: Install packages only when the apt process is not locked
-  apt:
-    name: foo
-    state: present
-  register: apt_action
-  retries: 100
-  until: apt_action is success or ('Failed to lock apt for exclusive operation' not in apt_action.msg and '/var/lib/dpkg/lock' not in apt_action.msg)
-
-
 '''
 
 RETURN = '''