[docs][backport][2.13] Backportapalooza 3-31 (#77438)

* add links.yml to collection structure docs (#77415)

* add links.yml to collection structure docs
* fix link
* Update docs/docsite/rst/dev_guide/developing_collections_structure.rst

(cherry picked from commit 8caa6efaab6ed50193b6595825902804b7a05d6c)

* Example is a single play, not a playbook

(cherry picked from commit bf8e186c68dc97f7410fab78635d4b15e79ce800)

* Fix list formatting (#77354)

(cherry picked from commit e918cfa588ff7b6c98c90fef2798250a26c94e01)

* Most Matrix channels are ansible.com and not .im (#77352)

(cherry picked from commit 6557a60d0832458b3584fde939d9f72b6227c10b)

* Docs cheatsheet - skeleton and ansible-playbook (#76655)

(cherry picked from commit 21addac5da57ca90480dde7feddbe3e2b0eae412)

Co-authored-by: rwhector <richard@walnut.gen.nz>
Co-authored-by: Christian Adamini <christian.adamini@invision.de>
Co-authored-by: bluikko <14869000+bluikko@users.noreply.github.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>

6 files changed, 70 insertions, 37 deletions

diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst
index 421982061d..d50be0e621 100644
--- a/docs/docsite/rst/community/communication.rst
+++ b/docs/docsite/rst/community/communication.rst
@@ -86,10 +86,10 @@ General channels
 
 The clickable links will take you directly to the relevant Matrix room in your browser; room/channel information is also given for use in other clients:
 
-- `Community social room and posting news for the Bullhorn newsletter <https://matrix.to:/#/#social:ansible.im>`_ - ``Matrix: #social:ansible.im | IRC: #ansible-social``
-- `General usage and support questions <https://matrix.to:/#/#users:ansible.im>`_ - ``Matrix: #users:ansible.im | IRC: #ansible``
-- `Discussions on developer topics and code related to features or bugs <https://matrix.to/#/#devel:ansible.im>`_ - ``Matrix: #devel:ansible.im | IRC: #ansible-devel``
-- `Discussions on community and collections related topics <https://matrix.to:/#/#community:ansible.im>`_ - ``Matrix: #community:ansible.im | IRC: #ansible-community``
+- `Community social room and posting news for the Bullhorn newsletter <https://matrix.to:/#/#social:ansible.com>`_ - ``Matrix: #social:ansible.com | IRC: #ansible-social``
+- `General usage and support questions <https://matrix.to:/#/#users:ansible.com>`_ - ``Matrix: #users:ansible.com | IRC: #ansible``
+- `Discussions on developer topics and code related to features or bugs <https://matrix.to/#/#devel:ansible.com>`_ - ``Matrix: #devel:ansible.com | IRC: #ansible-devel``
+- `Discussions on community and collections related topics <https://matrix.to:/#/#community:ansible.com>`_ - ``Matrix: #community:ansible.com | IRC: #ansible-community``
 - `For public community meetings <https://matrix.to/#/#meeting:ansible.im>`_ - ``Matrix: #meeting:ansible.im | IRC: #ansible-meeting``
    - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
 
@@ -100,28 +100,28 @@ Working groups
 
 Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda.
 
-- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.im <https://matrix.to:/#/#aws:ansible.im>`_ | IRC: ``#ansible-aws``
-- `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.im <https://matrix.to:/#/#lockdown:ansible.im>`_ | IRC: ``#ansible-lockdown``
-- `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.im <https://matrix.to:/#/#awx:ansible.im>`_ | IRC: ``#ansible-awx``
-- `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - Matrix: `#azure:ansible.im <https://matrix.to:/#/#azure:ansible.im>`_ | IRC: ``#ansible-azure``
-- `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ (including Meetups) - Matrix: `#community:ansible.im <https://matrix.to:/#/#community:ansible.im>`_ | IRC: ``#ansible-community``
-- `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - Matrix: `#container:ansible.im <https://matrix.to:/#/#container:ansible.im>`_ | IRC: ``#ansible-container``
-- `Contributor Experience Working Group <https://github.com/ansible/community/wiki/Contributor-Experience>`_ - Matrix: `#community:ansible.im <https://matrix.to:/#/#community:ansible.im>`_ | IRC: ``#ansible-community``
+- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.com <https://matrix.to:/#/#aws:ansible.com>`_ | IRC: ``#ansible-aws``
+- `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.com <https://matrix.to:/#/#lockdown:ansible.com>`_ | IRC: ``#ansible-lockdown``
+- `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.com <https://matrix.to:/#/#awx:ansible.com>`_ | IRC: ``#ansible-awx``
+- `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - Matrix: `#azure:ansible.com <https://matrix.to:/#/#azure:ansible.com>`_ | IRC: ``#ansible-azure``
+- `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ (including Meetups) - Matrix: `#community:ansible.com <https://matrix.to:/#/#community:ansible.com>`_ | IRC: ``#ansible-community``
+- `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - Matrix: `#container:ansible.com <https://matrix.to:/#/#container:ansible.com>`_ | IRC: ``#ansible-container``
+- `Contributor Experience Working Group <https://github.com/ansible/community/wiki/Contributor-Experience>`_ - Matrix: `#community:ansible.com <https://matrix.to:/#/#community:ansible.com>`_ | IRC: ``#ansible-community``
 - `DigitalOcean Working Group <https://github.com/ansible/community/wiki/Digital-Ocean>`_ - Matrix: `#digitalocean:ansible.im <https://matrix.to:/#/#digitalocean:ansible.im>`_ | IRC: ``#ansible-digitalocean``
-- `Diversity Working Group <https://github.com/ansible/community/wiki/Diversity>`_ - Matrix: `#diversity:ansible.im <https://matrix.to:/#/#diversity:ansible.im>`_ | IRC: ``#ansible-diversity``
-- `Docker Working Group <https://github.com/ansible/community/wiki/Docker>`_ - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `Documentation Working Group <https://github.com/ansible/community/wiki/Docs>`_ - Matrix: `#docs:ansible.im <https://matrix.to:/#/#docs:ansible.im>`_ | IRC: ``#ansible-docs``
-- `Galaxy Working Group <https://github.com/ansible/community/wiki/Galaxy>`_ - Matrix: `#galaxy:ansible.im <https://matrix.to:/#/#galaxy:ansible.im>`_ | IRC: ``#ansible-galaxy``
-- `JBoss Working Group <https://github.com/ansible/community/wiki/JBoss>`_ - Matrix: `#jboss:ansible.im <https://matrix.to:/#/#jboss:ansible.im>`_ | IRC: ``#ansible-jboss``
-- `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.im <https://matrix.to:/#/#kubernetes:ansible.im>`_ | IRC: ``#ansible-kubernetes``
-- `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.im <https://matrix.to:/#/#linode:ansible.im>`_ | IRC: ``#ansible-linode``
+- `Diversity Working Group <https://github.com/ansible/community/wiki/Diversity>`_ - Matrix: `#diversity:ansible.com <https://matrix.to:/#/#diversity:ansible.com>`_ | IRC: ``#ansible-diversity``
+- `Docker Working Group <https://github.com/ansible/community/wiki/Docker>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel``
+- `Documentation Working Group <https://github.com/ansible/community/wiki/Docs>`_ - Matrix: `#docs:ansible.com <https://matrix.to:/#/#docs:ansible.com>`_ | IRC: ``#ansible-docs``
+- `Galaxy Working Group <https://github.com/ansible/community/wiki/Galaxy>`_ - Matrix: `#galaxy:ansible.com <https://matrix.to:/#/#galaxy:ansible.com>`_ | IRC: ``#ansible-galaxy``
+- `JBoss Working Group <https://github.com/ansible/community/wiki/JBoss>`_ - Matrix: `#jboss:ansible.com <https://matrix.to:/#/#jboss:ansible.com>`_ | IRC: ``#ansible-jboss``
+- `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.com <https://matrix.to:/#/#kubernetes:ansible.com>`_ | IRC: ``#ansible-kubernetes``
+- `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.com <https://matrix.to:/#/#linode:ansible.com>`_ | IRC: ``#ansible-linode``
 - `Molecule Working Group <https://github.com/ansible/community/wiki/Molecule>`_ (`testing platform for Ansible playbooks and roles <https://molecule.readthedocs.io>`_) - Matrix: `#molecule:ansible.im <https://matrix.to:/#/#molecule:ansible.im>`_ | IRC: ``#ansible-molecule``
-- `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.im <https://matrix.to:/#/#network:ansible.im>`_ | IRC: ``#ansible-network``
-- `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_  - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.im <https://matrix.to:/#/#vmware:ansible.im>`_ | IRC: ``#ansible-vmware``
-- `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.im <https://matrix.to:/#/#windows:ansible.im>`_ | IRC: ``#ansible-windows``
-- `Ansible developer tools Group <https://github.com/ansible/community/wiki/Ansible-developer-tools>`_ - Matrix: `devtools:ansible.im <https://matrix.to/#/#devtools:ansible.im>`_ | IRC: ``#ansible-devtools``
+- `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.com <https://matrix.to:/#/#network:ansible.com>`_ | IRC: ``#ansible-network``
+- `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel``
+- `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_  - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel``
+- `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.com <https://matrix.to:/#/#vmware:ansible.com>`_ | IRC: ``#ansible-vmware``
+- `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.com <https://matrix.to:/#/#windows:ansible.com>`_ | IRC: ``#ansible-windows``
+- `Ansible developer tools Group <https://github.com/ansible/community/wiki/Ansible-developer-tools>`_ - Matrix: `#devtools:ansible.com <https://matrix.to/#/#devtools:ansible.com>`_ | IRC: ``#ansible-devtools``
 
 Want to `form a new Working Group <https://github.com/ansible/community/blob/master/WORKING-GROUPS.md>`_?
 
diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst
index 9eec5b7412..49ba8ed595 100644
--- a/docs/docsite/rst/community/reporting_bugs_and_features.rst
+++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst
@@ -38,17 +38,15 @@ If you find a bug, open an issue using the `issue template <https://github.com/a
 
 Fill out the issue template as completely and as accurately as possible. Include:
 
-  * your Ansible version
-  * the expected behavior
-  * the current behavior and why you think it is a bug
-  * what you've tried including the exact commands you were using or tasks you are running
-  * any relevant configurations and the components you used
-  * any relevant output plus ``ansible -vvvv`` (debugging) output
-  * the steps to reproduce the bug  
-    * Use a minimal reproducible example and comments describing examples
-    * Preserve formatting using `code blocks  <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_ when sharing YAML in playbooks.
-
-For multiple-file content, use gist.github.com, which is more durable than pastebin content.
+* your Ansible version
+* the expected behavior and what you've tried (including the exact commands you were using or tasks you are running)
+* the current behavior and why you think it is a bug
+* the steps to reproduce the bug 
+* a minimal reproducible example and comments describing examples
+* any relevant configurations and the components you used
+* any relevant output plus ``ansible -vvvv`` (debugging) output
+
+Make sure to preserve formatting using `code blocks  <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_ when sharing YAML in playbooks. For multiple-file content, use gist.github.com, which is more durable than pastebin content.
 
 .. _request_features:
 
diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst
index de6629b34c..0c3f7392f1 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst
@@ -70,7 +70,9 @@ For community collections included in the Ansible PyPI package, docs.ansible.com
      toctree:
        - scenario_guide
 
-The index page of the documentation for your collection displays the title you define in ``docs/docsite/extra-docs.yml`` with a link to your extra documentation. For an example, see the `community.docker collection repo <https://github.com/ansible-collections/community.docker/tree/main/docs/docsite>`_ and the `community.docker collection documentation <https://docs.ansible.com/ansible/latest/collections/community/docker/index.html>`_. 
+The index page of the documentation for your collection displays the title you define in ``docs/docsite/extra-docs.yml`` with a link to your extra documentation. For an example, see the `community.docker collection repo <https://github.com/ansible-collections/community.docker/tree/main/docs/docsite>`_ and the `community.docker collection documentation <https://docs.ansible.com/ansible/latest/collections/community/docker/index.html>`_.
+
+You can add extra links to your collection index page and plugin pages with the ``docs/docsite/links.yml`` file. This populates the links under `Description and Communications <https://docs.ansible.com/ansible/devel/collections/community/dns/index.html#plugins-in-community-dns>`_ headings as well as links at the end of the individual plugin pages. See the `collection_template links.yml file <https://github.com/ansible-collections/collection_template/blob/main/docs/docsite/links.yml>`_ for a complete description of the structure and use of this file to create links.
 
 Plugin and module documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/docsite/rst/user_guide/cheatsheet.rst b/docs/docsite/rst/user_guide/cheatsheet.rst
new file mode 100644
index 0000000000..11acc85f7c
--- /dev/null
+++ b/docs/docsite/rst/user_guide/cheatsheet.rst
@@ -0,0 +1,31 @@
+.. _cheatsheet:
+
+**********************
+Ansible CLI cheatsheet
+**********************
+
+This page shows one or more examples of each Ansible command line utility with some common flags added and a link to the full documentation for the command. This page offers a quick reminder of some common use cases only - it may be out of date or incomplete or both. For canonical documentation, follow the links to the CLI pages.
+
+.. contents::
+   :local:
+
+ansible-playbook
+================
+
+.. code-block:: bash
+
+   ansible-playbook -i /path/to/my_inventory_file -u my_connection_user -k /path/to/my_ssh_key -f 3 -T 30 -t my_tag -m /path/to/my_modules -b -K my_playbook.yml
+
+Loads ``my_playbook.yml`` from the current working directory and:
+  - ``-i`` - uses ``my_inventory_file`` in the path provided for :ref:`inventory <intro_inventory>` to match the :ref:`pattern <intro_patterns>`.
+  - ``-u`` - connects :ref:`over SSH <connections>` as ``my_connection_user``.
+  - ``-k`` - uses ``my_ssh_key`` in the path provided for SSH authentication.
+  - ``-f`` - allocates 3 :ref:`forks <playbooks_strategies>`.
+  - ``-T`` - sets a 30-second timeout.
+  - ``-t`` - runs only tasks marked with the :ref:`tag <tags>` ``my_tag``.
+  - ``-m`` - loads :ref:`local modules <developing_locally>` from ``/path/to/my/modules``.
+  - ``-b`` - executes with elevated privileges (uses :ref:`become <become>`).
+  - ``-K`` - prompts the user for the become password.
+
+See :ref:`ansible-playbook` for detailed documentation.
+
diff --git a/docs/docsite/rst/user_guide/index.rst b/docs/docsite/rst/user_guide/index.rst
index 733078e077..3d162967f1 100644
--- a/docs/docsite/rst/user_guide/index.rst
+++ b/docs/docsite/rst/user_guide/index.rst
@@ -22,6 +22,7 @@ Getting started
 
 * I'm ready to learn about Ansible. What :ref:`basic_concepts` do I need to learn?
 * I want to use Ansible without writing a playbook. How do I use :ref:`ad hoc commands <intro_adhoc>`?
+* I'm running an Ansible command and forgot which flags to use. Do you have a :ref:`cheatsheet`?
 
 Writing tasks, plays, and playbooks
 ===================================
@@ -91,6 +92,7 @@ If you prefer to read the entire User Guide, here's a list of the pages in order
    :maxdepth: 2
 
    quickstart
+   cheatsheet
    basic_concepts
    intro_getting_started
    intro_adhoc
diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
index 583599fcd6..e5b6938c05 100644
--- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
+++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
@@ -406,7 +406,7 @@ Passing different parameters
 
 If you pass different parameters in each role definition, Ansible runs the role more than once. Providing different variable values is not the same as passing different role parameters. You must use the ``roles`` keyword for this behavior, since ``import_role`` and ``include_role`` do not accept role parameters.
 
-This playbook runs the ``foo`` role twice:
+This play runs the ``foo`` role twice:
 
 .. code-block:: yaml