Doc backportapalooza 2

changelogs/fragments/70045-ansible-doc-yaml-anchors.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "ansible-doc - improve man page formatting to avoid problems when YAML anchors are used (https://github.com/ansible/ansible/pull/70045)."

changelogs/fragments/with_seq_example.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- Add an example for using var in with_sequence (https://github.com/ansible/ansible/issues/68836).

docs/docsite/keyword_desc.yml

@@ -6,23 +6,25 @@ args: "A secondary way to add arguments into a task. Takes a dictionary in which
 always: List of tasks, in a block, that execute no matter if there is an error in the block or not.
 any_errors_fatal: Force any un-handled task errors on any host to propagate to all hosts and end the play.
 async: Run a task asynchronously if the C(action) supports this; value is maximum runtime in seconds.
-become: Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
+become: Boolean that controls if privilege escalation is used or not on :term:`Task` execution. Implemented by the become plugin. See :ref:`become_plugins`.
+become_exe: Path to the executable used to elevate privileges. Implemented by the become plugin. See :ref:`become_plugins`.
 become_flags: A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
 become_method: Which method of privilege escalation to use (such as sudo or su).
 become_user: "User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user."
 block: List of tasks in a block.
 changed_when: "Conditional expression that overrides the task's normal 'changed' status."
-check_mode: |
-    A boolean that controls if a task is executed in 'check' mode
+check_mode: A boolean that controls if a task is executed in 'check' mode. See :ref:`check_mode_dry`.
+collections: |
 
-    .. seealso:: :ref:`check_mode_dry`
+    List of collection namespaces to search for modules, plugins, and roles. See :ref:`collections_using_playbook`
 
-connection: |
-    Allows you to change the connection plugin used for tasks to execute on the target.
+    .. note::
 
-    .. seealso:: :ref:`using_connection`
+        Tasks within a role do not inherit the value of ``collections`` from the play. To have a role search a list of collections, use the ``collections`` keyword in ``meta/main.yml`` within a role.
 
-debugger: Enable debugging tasks based on state of the task result. See :ref:`playbook_debugger`
+
+connection: Allows you to change the connection plugin used for tasks to execute on the target. See :ref:`using_connection`.
+debugger: Enable debugging tasks based on state of the task result. See :ref:`playbook_debugger`.
 delay: Number of seconds to delay between retries. This setting is only used in combination with :term:`until`.
 delegate_facts: Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
 delegate_to: Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -613,6 +613,59 @@ Now you can use this checkout of ``community.general`` in playbooks and roles wi
 
 For collections hosted in the ``ansible_collections`` GitHub org, create a branch and commit your changes on the branch. When you are done (remember to add tests, see :ref:`testing_collections`), push your changes to your fork of the collection and create a Pull Request. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
 
+.. _collection_changelogs:
+
+Generating changelogs for a collection
+======================================
+
+We recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs for your collection. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
+
+.. note::
+
+	Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
+
+If your collection is part of Ansible but you are not using this tool, your collection should include the properly formatted ``changelog.yaml`` file or your changelogs will not be part of the combined Ansible CHANGELOG.rst and Porting Guide at release.  See the `changlog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
+
+Understanding antsibull-changelog
+---------------------------------
+
+The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
+
+See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
+
+.. note::
+
+	The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
+
+Generating changelogs
+---------------------
+
+To initialize changelog generation:
+
+#. Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`.
+#. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
+#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
+
+To generate changelogs from the changelog fragments you created:
+
+#. Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
+#. Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
+
+.. note::
+
+  Add the  ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.  
+
+
+Porting Guide entries
+----------------------
+
+The following changelog fragment categories are consumed by the Ansible changelog generator into the Ansible Porting Guide:
+
+* ``major_changes``
+* ``breaking_changes``
+* ``deprecated_features``
+* ``removed_features``
+
 
 .. seealso::
 

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -193,6 +193,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 :seealso:
 
   * A list of references to other modules, documentation or Internet resources
+  * In Ansible 2.10 and later, references to modules must use  the FQCN or ``ansible.builtin`` for modules in ``ansible-base``.
   * A reference can be one of the following formats:
 
 
@@ -201,10 +202,10 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
         seealso:
 
         # Reference by module name
-        - module: aci_tenant
+        - module: cisco.aci.aci_tenant
 
         # Reference by module name, including description
-        - module: aci_tenant
+        - module: cisco.aci.aci_tenant
           description: ACI module to create tenants on a Cisco ACI fabric.
 
         # Reference by rST documentation anchor
@@ -232,18 +233,23 @@ You can link from your module documentation to other module docs, other resource
 * ``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.
 * ``I()`` for option names. For example: ``Required if I(state=present).``
 * ``C()`` for files and option values. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.``
-* ``M()`` for module names. For example: ``See also M(win_copy) or M(win_template).``
+* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
 
 .. note::
 
-  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). 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.
+  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(community.kubernetes collection, plugins_in_community.kubernetes) for information on managing kubernetes clusters.``
+        -``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
+
 
 .. note::
 
-    - To refer a group of modules, use ``C(..)``, e.g. ``Refer to the C(win_*) modules.``
-    - Because it stands out better, using ``seealso`` is preferred for general references over the use of notes or adding links to the description.
+   Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description.
 
 .. _module_docs_fragments:
 

docs/docsite/rst/network/user_guide/platform_index.rst

@@ -59,35 +59,61 @@ Settings by Platform
     --------------------------------------------------------  ------------------------------------------
     Network OS                       ``ansible_network_os:``  network_cli  netconf  httpapi  local
     ===============================  =======================  ===========  =======  =======  ===========
-    Arista EOS `[†]`_                ``eos``                  ✓                     ✓        ✓
-    Cisco ASA                        ``asa``                  ✓                              ✓
-    Cisco IOS `[†]`_                 ``ios``                  ✓                              ✓
-    Cisco IOS XR `[†]`_              ``iosxr``                ✓                              ✓
-    Cisco NX-OS `[†]`_               ``nxos``                 ✓                     ✓        ✓
-    Cloudengine OS `[†]`_            ``ce``                   ✓            ✓                 ✓
-    Dell OS6                         ``dellos6``              ✓                              ✓
-    Dell OS9                         ``dellos9``              ✓                              ✓
-    Dell OS10                        ``dellos10``             ✓                              ✓
-    Ericsson ECCLI                   ``eric_eccli``           ✓                              ✓
-    Extreme EXOS                     ``exos``                 ✓                     ✓
-    Extreme IronWare                 ``ironware``             ✓                              ✓
-    Extreme NOS                      ``nos``                  ✓
-    Extreme SLX-OS                   ``slxos``                ✓
-    Extreme VOSS                     ``voss``                 ✓
-    F5 BIG-IP                                                                                ✓
-    F5 BIG-IQ                                                                                ✓
-    Junos OS `[†]`_                  ``junos``                ✓            ✓                 ✓
-    Lenovo CNOS                      ``cnos``                 ✓                              ✓
-    Lenovo ENOS                      ``enos``                 ✓                              ✓
-    Meraki                           ``meraki``                                              ✓
-    MikroTik RouterOS                ``routeros``             ✓
-    Nokia SR OS                      ``sros``                 ✓                              ✓
-    Pluribus Netvisor                ``netvisor``             ✓
-    Ruckus ICX `[†]`_                ``icx``                  ✓
-    VyOS `[†]`_                      ``vyos``                 ✓                              ✓
+    `Arista EOS`_ `[†]`_                ``eos``                  ✓                     ✓        ✓
+    `Cisco ASA`_ `[†]`_                      ``asa``                  ✓                              ✓
+    `Cisco IOS`_ `[†]`_                 ``ios``                  ✓                              ✓
+    `Cisco IOS XR`_ `[†]`_              ``iosxr``                ✓                              ✓
+    `Cisco NX-OS`_ `[†]`_               ``nxos``                 ✓                     ✓        ✓
+    `Cloudengine OS`_                   ``ce``                   ✓            ✓                 ✓
+    `Dell OS6`_                         ``dellos6``              ✓                              ✓
+    `Dell OS9`_                        ``dellos9``              ✓                              ✓
+    `Dell OS10`_                        ``dellos10``             ✓                              ✓
+    `Ericsson ECCLI`_                   ``eric_eccli``           ✓                              ✓
+    `Extreme EXOS`_                     ``exos``                 ✓                     ✓
+    `Extreme IronWare`_                 ``ironware``             ✓                              ✓
+    `Extreme NOS`_                     ``nos``                  ✓
+    `Extreme SLX-OS`_                   ``slxos``                ✓
+    `Extreme VOSS`_                     ``voss``                 ✓
+    `F5 BIG-IP`_                                                                                ✓
+    `F5 BIG-IQ`_                                                                                ✓
+    `Junos OS`_ `[†]`_                  ``junos``                ✓            ✓                 ✓
+    `Lenovo CNOS`_                      ``cnos``                 ✓                              ✓
+    `Lenovo ENOS`_                      ``enos``                 ✓                              ✓
+    `Meraki`_                           ``meraki``                                              ✓
+    `MikroTik RouterOS`_                ``routeros``             ✓
+    `Nokia SR OS`_                      ``sros``                 ✓                              ✓
+    `Pluribus Netvisor`_                ``netvisor``             ✓
+    `Ruckus ICX`_                       ``icx``                  ✓
+    `VyOS`_ `[†]`_                      ``vyos``                 ✓                              ✓
     OS that supports Netconf `[†]`_  ``<network-os>``                      ✓                 ✓
     ===============================  =======================  ===========  =======  =======  ===========
 
+.. _Arista EOS: https://galaxy.ansible.com/arista/eos
+.. _Cisco ASA: https://galaxy.ansible.com/cisco/asa
+.. _Cisco IOS: https://galaxy.ansible.com/cisco/ios
+.. _Cisco IOS XR: https://galaxy.ansible.com/cisco/iosxr
+.. _Cisco NX-OS: https://galaxy.ansible.com/cisco/nxos
+.. _Cloudengine OS: https://galaxy.ansible.com/community/network
+.. _Dell OS6: https://github.com/ansible-collections/dellemc.os6
+.. _Dell OS9: https://github.com/ansible-collections/dellemc.os9
+.. _Dell OS10: https://galaxy.ansible.com/dellemc_networking/os10
+.. _Ericsson ECCLI: https://galaxy.ansible.com/community/network
+.. _Extreme EXOS: https://galaxy.ansible.com/community/network
+.. _Extreme IronWare: https://galaxy.ansible.com/community/network
+.. _Extreme NOS: https://galaxy.ansible.com/community/network
+.. _Extreme SLX-OS: https://galaxy.ansible.com/community/network
+.. _Extreme VOSS: https://galaxy.ansible.com/community/network
+.. _F5 BIG-IP: https://galaxy.ansible.com/f5networks/f5_modules
+.. _F5 BIG-IQ: https://galaxy.ansible.com/f5networks/f5_modules
+.. _Junos OS: https://galaxy.ansible.com/junipernetworks/junos
+.. _Lenovo CNOS: https://galaxy.ansible.com/community/network
+.. _Lenovo ENOS: https://galaxy.ansible.com/community/network
+.. _Meraki: https://galaxy.ansible.com/cisco/meraki
+.. _MikroTik RouterOS: https://galaxy.ansible.com/community/network
+.. _Nokia SR OS: https://galaxy.ansible.com/community/network
+.. _Pluribus Netvisor: https://galaxy.ansible.com/community/network
+.. _Ruckus ICX: https://galaxy.ansible.com/community/network
+.. _VyOS: https://galaxy.ansible.com/vyos/vyos
 .. _`[†]`:
 
 **[†]** Maintained by Ansible Network Team

docs/docsite/rst/scenario_guides/guide_vultr.rst

@@ -93,7 +93,7 @@ Since `Vultr <https://www.vultr.com>`_ offers a public API, the execution of the
           region: New Jersey
 
 
-From that point on, only you creativity is the limit. Make sure to read the documentation of the `available modules <https://docs.ansible.com/ansible/latest/modules/list_of_cloud_modules.html#vultr>`_.
+From that point on, only your creativity is the limit. Make sure to read the documentation of the `available modules <https://docs.ansible.com/ansible/latest/modules/list_of_cloud_modules.html#vultr>`_.
 
 
 Dynamic Inventory

docs/docsite/rst/user_guide/intro_getting_started.rst

@@ -50,8 +50,11 @@ Beyond the basics
 You can override the default remote user name in several ways, including:
 
 * passing the ``-u`` parameter at the command line
+
 * setting user information in your inventory file
+
 * setting user information in your configuration file
+
 * setting environment variables
 
 See :ref:`general_precedence_rules` for details on the (sometimes unintuitive) precedence of each method of passing user information. You can read more about connections in :ref:`connections`.

docs/docsite/rst/user_guide/playbooks.rst

@@ -1,6 +1,6 @@
 .. _working_with_playbooks:
 
-Working With Playbooks
+Working with playbooks
 ======================
 
 Playbooks are Ansible's configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.