summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorSandra McCann <samccann@redhat.com>2022-10-25 16:36:03 -0400
committerGitHub <noreply@github.com>2022-10-25 15:36:03 -0500
commit795ac8993b35edc208e33b8033b382cfe240dfee (patch)
treea2c354a348596d96c6f075270fd85aa007ab2516 /docs
parenta76163ca3c42b32adcd613a1a1d343320bd30fa4 (diff)
downloadansible-795ac8993b35edc208e33b8033b382cfe240dfee.tar.gz
Backportapalooza 10 20 (#79180)
* docs: fix typos (#79082) (cherry picked from commit ad5d9843d651dd35287e2ad1ed0f57439e864e7e) * Docs: syntax error in Parsing semi-structured text with Ansible (#79085) (cherry picked from commit 7d6984618da4c481b2980c1fe4b5b0fa95ae50da) * Added code-block wrappers in implicit_localhost.rst (#79086) Fixes #79031 (cherry picked from commit 8ecfb7c6d8384365cf34c893f6e6faad421f3bc3) * Misc Typo fixes (#79088) (cherry picked from commit a48c4422759605a95e74d0a7e8456ad35f72caa8) * Add code-block wrappers to code examples in playbooks_filters.rst (#79093) Fixes #79029 (cherry picked from commit dfef3260a52a0d1038ed0c6840a5d40a4dbfeeb3) * Apply minor formatting changes to "playbooks directory" section (#79092) (cherry picked from commit 1286b7d42ee9053fa016812eddce40ce40978581) * Made changes to notes on #L9 and #L21 (#79173) (cherry picked from commit d6c268378f248c5892298627ad74562593c6300b) * Update communication.rst (#79172) grammar fixes (cherry picked from commit 1a6cfa8203e932019d1e7eb1d2485f1fe15c7f2c) * Update contributor_path.rst (#79170) grammar fixes (cherry picked from commit 64d5c6cc3af4aa3e39648442e5ed1823543452dc) * Update overview_architecture.rst (#79161) Add missing right parenthesis (cherry picked from commit 89af4e6e31f83f2f51a6e7eeedafcf1b4c2d7b5f) * Added the emphasize changelog (#79160) Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua> (cherry picked from commit b7eb0670907637ab2a9c0f40dfe5dc46eb7efbe0) * minor changes in documentation (#79114) (cherry picked from commit cc3abae532ac9d4638bc2299cfc61dd1426658f3) * Setting indentation correctly in the Example section (#79072) (cherry picked from commit 1182059d462c98d908cd0caaedd209aff6acc3a6) * docs: cgroupsv1 is required for ansible-test with docker (#79066) (cherry picked from commit ae38628404598832c5e652ec805e89a62c24e2c4) * Change occurance yes/no to true/false (#79035) (cherry picked from commit 551f5a375327347b26d352c3cbbc93afc93a2402) Co-authored-by: KIDANI Akito <a.kid.1985@gmail.com> Co-authored-by: taso <74918216+tasoint@users.noreply.github.com> Co-authored-by: 12-malak <73274076+12-malak@users.noreply.github.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Sharif Nassar <mrwacky42@users.noreply.github.com> Co-authored-by: NitrogenPointBlue <110332643+NitrogenPointBlue@users.noreply.github.com> Co-authored-by: Aysha Muhammed <64032658+Aysha-py@users.noreply.github.com> Co-authored-by: Goodness Chris-Ugari <goodnesschrisugari@yahoo.com> Co-authored-by: Jack Lin <46962923+blueskyson@users.noreply.github.com> Co-authored-by: Tabah Baridule M <dulemartins07@gmail.com> Co-authored-by: trolzen <trolzen@gmail.com> Co-authored-by: Bart Dorlandt <bart@bamweb.nl> Co-authored-by: Chris Smart <distroguy@gmail.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/docsite/rst/community/collection_contributors/collection_integration_about.rst2
-rw-r--r--docs/docsite/rst/community/collection_contributors/collection_integration_add.rst6
-rw-r--r--docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst2
-rw-r--r--docs/docsite/rst/community/collection_development_process.rst2
-rw-r--r--docs/docsite/rst/community/communication.rst2
-rw-r--r--docs/docsite/rst/community/contributor_path.rst16
-rw-r--r--docs/docsite/rst/community/create_pr_quick_start.rst24
-rw-r--r--docs/docsite/rst/community/how_can_I_help.rst2
-rw-r--r--docs/docsite/rst/community/index.rst2
-rw-r--r--docs/docsite/rst/community/reporting_collections.rst4
-rw-r--r--docs/docsite/rst/dev_guide/developing_collections_structure.rst4
-rw-r--r--docs/docsite/rst/dev_guide/developing_python_3.rst2
-rw-r--r--docs/docsite/rst/dev_guide/overview_architecture.rst2
-rw-r--r--docs/docsite/rst/inventory/implicit_localhost.rst9
-rw-r--r--docs/docsite/rst/network/getting_started/first_playbook.rst6
-rw-r--r--docs/docsite/rst/network/user_guide/cli_parsing.rst2
-rw-r--r--docs/docsite/rst/playbook_guide/playbooks_filters.rst4
-rw-r--r--docs/docsite/rst/reference_appendices/python_3_support.rst4
18 files changed, 53 insertions, 42 deletions
diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst
index 652b11f631..d011fdb064 100644
--- a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst
+++ b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst
@@ -128,7 +128,7 @@ To check a task:
#. Expected return values.
2. If the module changes the system state, check the actual system state using at least one other module. For example, if the module changes a file, we can check that the file has been changed by checking its checksum with the :ref:`stat <ansible_collections.ansible.builtin.stat_module>` module before and after the test tasks.
-3. Run the same task with ``check_mode: yes`` if check-mode is supported by the module. Check with other modules that the actual system state has not been changed.
+3. Run the same task with ``check_mode: true`` if check-mode is supported by the module. Check with other modules that the actual system state has not been changed.
4. Cover cases when the module must fail. Use the ``ignore_errors: true`` option and check the returned message with the ``assert`` module.
Example:
diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
index b73c032660..ad30b02773 100644
--- a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
+++ b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst
@@ -36,7 +36,7 @@ We should basically do the following:
1. Clone the collection to the ``~/ansible_collections/community.abstract`` directory on your local machine.
-2. From the ``~/ansble_collections/community.abstract`` directory, create directories for the ``setup`` target:
+2. From the ``~/ansible_collections/community.abstract`` directory, create directories for the ``setup`` target:
.. code-block:: bash
@@ -63,7 +63,7 @@ This is a very simplified example.
4. Add the target for the module you are testing.
-Let's say the module is called ``abstact_service_info``. Create the following directory structure in the target:
+Let's say the module is called ``abstract_service_info``. Create the following directory structure in the target:
.. code-block:: bash
@@ -90,7 +90,7 @@ Add the following to ``tests/integration/targets/abstract_service_info/tasks/mai
.. code-block:: yaml
- name: Fetch info from abstract service
- anstract_service_info:
+ abstract_service_info:
host: 127.0.0.1 # We assume the service accepts local connection by default
port: 1234 # We assume that the service is listening this port by default
register: result # This variable will contain the returned JSON including the server version
diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst
index 9cc7054fb9..d48cb24fee 100644
--- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst
+++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst
@@ -213,7 +213,7 @@ Publishing the collection
Releasing patch versions
-------------------------
-The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently``0`` snce patch releases are uncommon.
+The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently``0`` since patch releases are uncommon.
Releasing when more minor versions are expected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/docsite/rst/community/collection_development_process.rst b/docs/docsite/rst/community/collection_development_process.rst
index afe693a265..2da3964925 100644
--- a/docs/docsite/rst/community/collection_development_process.rst
+++ b/docs/docsite/rst/community/collection_development_process.rst
@@ -46,6 +46,8 @@ We do not merge every PR. See :ref:`collection_quickstart` for tips to make you
Creating changelog fragments
-----------------------------
+Most changelogs should emphasize the impact of the change on the end user of the feature or collection, unless the change impacts developers directly. Consider what the user needs to know about this change and write the changelog to convey that detail.
+
Changelogs help users and developers keep up with changes to Ansible collections. Many collections build changelogs for each release from fragments. For collections that use this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug.
You do not need a changelog fragment for PRs that:
diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst
index f6232a748f..8b224d9f56 100644
--- a/docs/docsite/rst/community/communication.rst
+++ b/docs/docsite/rst/community/communication.rst
@@ -67,7 +67,7 @@ The Ansible community maintains several IRC channels on `irc.libera.chat <https:
IRC chat supports:
-* no persistence (you only see messages when you are logged on, unless you add a bouncer)
+* no persistence (you only see messages when you are logged on unless you add a bouncer)
* simple text interface
* bridging from Matrix
diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst
index aced42b31d..6c92d3bb13 100644
--- a/docs/docsite/rst/community/contributor_path.rst
+++ b/docs/docsite/rst/community/contributor_path.rst
@@ -2,7 +2,7 @@
Contributor path
****************
-This section describes the contributor journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation.
+This section describes the contributor's journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation.
Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it's feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project.
@@ -39,16 +39,16 @@ Specific knowledge for code developers
Code development requires the most technical knowledge. Let's sort out what an Ansible developer should learn.
-You should understand at least *basics* of the following tools:
+You should understand at least the *basics* of the following tools:
- `Python programming language <https://docs.python.org/3/tutorial/>`_
- `Git <https://git-scm.com/docs/gittutorial>`_
- `GitHub collaborative development model through forks and pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models>`_
-You can learn these tools more in depth when working on your first contributions.
+You can learn these tools more in-depth when working on your first contributions.
-Each Ansible project has its own set of contributor guidelines. Familarize yourself with these as you prepare your first contributions.
+Each Ansible project has its own set of contributor guidelines. Familiarize yourself with these as you prepare your first contributions.
* :ref:`Ansible Core development <developer_guide>`.
* :ref:`Ansible collection development <developing_collections>` and the collection-level contributor guidelines in the collection repository.
@@ -72,18 +72,18 @@ See :ref:`communication` for ways to communicate and engage with the Ansible com
Teach others
============
-Share your experience with other contributors through `improving documentation <ommunity_documentation_contributions>`, answering question from other contributors and users on `Matrix/Libera.Chat IRC <communicate>`, giving advice in issues and pull requests, and discussing the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
+Share your experience with other contributors through :ref:`improving documentation<community_documentation_contributions>`, and answering questions from other contributors and users on :ref:`Matrix/Libera.Chat IRC<communication>`, giving advice on issues and pull requests, and discussing `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
Become a collection maintainer
===============================
If you are a code contributor to a collection, you can get extended permissions in the repository and become a maintainer. A collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and showed themselves as a specialist in the related area. See :ref:`maintainers` for details.
-For some collections that use the `collection bot <https://github.com/ansible-community/collection_bot>`_ , such as `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_, you can have different levels of access and permissions.
+For some collections that use the `collection bot <https://github.com/ansible-community/collection_bot>`_, such as `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_, you can have different levels of access and permissions.
* `module_maintainers` - The stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights.
* supershipit permissions - Similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository.
-* ``triage`` - Access to the repository that allows contributors manage issues and pull requests.
+* ``triage`` - Access to the repository that allows contributors to manage issues and pull requests.
* ``write`` access to the repository also known as ``commit``. In other words, become a committer. This access level allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the :ref:`maintainers`.
For information about permission levels, see the `GitHub official documentation <https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization>`_.
@@ -95,7 +95,7 @@ Become a steering committee member
You do NOT have to be a programmer to become a steering committee member.
-The :ref:`Steering Committee <community_steering_committee>` member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general.
+The :ref:`Steering Committee <community_steering_committee>` member status reflects the highest level of trust which allows contributors to lead the project by making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general.
To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should:
diff --git a/docs/docsite/rst/community/create_pr_quick_start.rst b/docs/docsite/rst/community/create_pr_quick_start.rst
index d06f58ddd7..083a1f2b7e 100644
--- a/docs/docsite/rst/community/create_pr_quick_start.rst
+++ b/docs/docsite/rst/community/create_pr_quick_start.rst
@@ -92,7 +92,7 @@ Change the code
.. note::
- Do NOT mix several bugfixes or features that are not tightly-related in one pull request. Use separate pull requests for different changes.
+ Do NOT mix several bug fixes or features that are not tightly related in one pull request. Use separate pull requests for different changes.
You should start with writing integration and unit tests if applicable. These can verify the bug exists (prior to your code fix) and verify your code fixed that bug once the tests pass.
@@ -113,7 +113,7 @@ The ``main.yml`` file holds test tasks and includes other test files.
Look for a suitable test file to integrate your tests or create and include a dedicated test file.
You can use one of the existing test files as a draft.
-When fixing a bug, write a task which reproduces the bug from the issue.
+When fixing a bug, write a task that reproduces the bug from the issue.
Put the reported case in the tests, then run integration tests with the following command:
@@ -121,16 +121,16 @@ Put the reported case in the tests, then run integration tests with the followin
$ ansible-test integration name_of_test_subdirectory --docker -v
-For example, if the tests files you changed are stored in ``tests/integration/targets/test_mysql_user/``, the command is as follows:
+For example, if the test files you changed are stored in ``tests/integration/targets/test_mysql_user/``, the command is as follows:
.. code-block:: bash
$ ansible-test integration test_mysql_user --docker -v
-You can use the ``-vv`` or ``-vvv`` argument, if you need more detailed output.
+You can use the ``-vv`` or ``-vvv`` argument if you need more detailed output.
In the examples above, the default test image is automatically downloaded and used to create and run a test container.
-Use the default test image for platform independent integration tests such as those for cloud modules.
+Use the default test image for platform-independent integration tests such as those for cloud modules.
If you need to run the tests against a specific distribution, see the :ref:`list of supported container images <test_container_images>`. For example:
@@ -145,7 +145,7 @@ If you need to run the tests against a specific distribution, see the :ref:`list
If the tests ran successfully, there are usually two possible outcomes:
- If the bug has not appeared and the tests have passed successfully, ask the reporter to provide more details. It may not be a bug or can relate to a particular software version used or specifics of the reporter's local environment configuration.
-- The bug has appeared and the tests has failed as expected showing the reported symptoms.
+- The bug has appeared and the tests have failed as expected showing the reported symptoms.
Fix the bug
=============
@@ -155,6 +155,8 @@ See :ref:`module_contribution` for some general guidelines about Ansible module
Test your changes
=================
+ If using the ``docker`` CLI program, the host must be configured to use cgroupsv1 (this is not required for ``podman``). This can be done by adding ``systemd.unified_cgroup_hierarchy=0`` to the kernel boot arguments (requires bootloader config update and reboot).
+
1. Install ``flake8`` (``pip install flake8``, or install the corresponding package on your operating system).
1. Run ``flake8`` against a changed file:
@@ -164,7 +166,7 @@ Test your changes
$ flake8 path/to/changed_file.py
- This shows unused imports, which is not shown by sanity tests, as well as other common issues.
+ This shows unused imports, which are not shown by sanity tests, as well as other common issues.
Optionally, you can use the ``--max-line-length=160`` command-line argument.
2. Run sanity tests:
@@ -193,7 +195,7 @@ Test your changes
There are two possible outcomes:
-- They have failed. Look at the output of the command. Fix the problem place in the code and run again. Repeat the cycle until the tests pass.
+- They have failed. Look at the output of the command. Fix the problem in the code and run again. Repeat the cycle until the tests pass.
- They have passed. Remember they failed originally? Our congratulations! You have fixed the bug.
In addition to the integration tests, you can also cover your changes with unit tests. This is often required when integration tests are not applicable to the collection.
@@ -234,7 +236,7 @@ Submit a pull request
GitHub is tracking your fork, so it should see the new branch in it and automatically offer to create a pull request. Sometimes GitHub does not do it, and you should click the :guilabel:`New pull request` button yourself. Then choose :guilabel:`compare across forks` under the :guilabel:`Compare changes` title.
-5.Choose your repository and the new branch you pushed in the right drop-down list. Confirm.
+5. Choose your repository and the new branch you pushed in the right drop-down list. Confirm.
a. Fill out the pull request template with all information you want to mention.
@@ -263,9 +265,9 @@ Submit a pull request
7. Verify the CI tests pass that run automatically on Red Hat infrastructure after every commit.
- You will see the CI status in the bottom of your pull request. If they are green and you think that you do not want to add more commits before someone should take a closer look at it, remove ``[WIP]`` from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review".
+ You will see the CI status at the bottom of your pull request. If they are green and you think that you do not want to add more commits before someone should take a closer look at it, remove ``[WIP]`` from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review".
-8. Wait for reviews. You can also ask for review in the ``#ansible-community`` :ref:`Matrix/Libera.Chat IRC channel <communication_irc>`.
+8. Wait for reviews. You can also ask for a review in the ``#ansible-community`` :ref:`Matrix/Libera.Chat IRC channel <communication_irc>`.
9. If the pull request looks good to the community, committers will merge it.
diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst
index ceeea05f46..66f55d1898 100644
--- a/docs/docsite/rst/community/how_can_I_help.rst
+++ b/docs/docsite/rst/community/how_can_I_help.rst
@@ -61,7 +61,7 @@ Review and submit pull requests
As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process <community_development_process>` to learn how to get your code accepted into Ansible.
-Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternately, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
+Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternatively, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
Become a collection maintainer
==============================
diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst
index e8ae75708b..b5ddb51d65 100644
--- a/docs/docsite/rst/community/index.rst
+++ b/docs/docsite/rst/community/index.rst
@@ -12,7 +12,7 @@ Ansible Community Guide
Welcome to the Ansible Community Guide!
-The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary to Ansible's continued success.
+The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary for Ansible's continued success.
.. _community_toc:
diff --git a/docs/docsite/rst/community/reporting_collections.rst b/docs/docsite/rst/community/reporting_collections.rst
index 806ce6e4cb..1d8c2e60f9 100644
--- a/docs/docsite/rst/community/reporting_collections.rst
+++ b/docs/docsite/rst/community/reporting_collections.rst
@@ -31,6 +31,6 @@ Requesting a feature
====================
Before you request a feature, check what is :ref:`planned for future Ansible Releases <roadmaps>`.
-The best way to get a feature into an Ansible collection is to :ref:`submit a pull request <community_pull_requests>`, either against ansible-core or against a collection. See also :ref:`ansible_collection_merge_requirements`.
+The best way to get a feature into an Ansible collection is to :ref:`submit a pull request <community_pull_requests>`, either against ansible-core or against a collection. See also the :ref:`ansible_collection_merge_requirements`.
-You can also submit a feature request through opening an issue in the collection repository.
+You can also submit a feature request by opening an issue in the collection repository.
diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst
index 997b0ad014..77d4e8bf56 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst
@@ -189,10 +189,10 @@ You can have most of the subdirectories you would expect, such ``files/``, ``var
Also, playbooks within a collection follow the same guidelines as any playbooks except for these few adjustments:
- - Directory: It must be in ``/playbooks directory``.
+ - Directory: It must be in the ``playbooks/`` directory.
- Hosts: The host should be defined as a variable so the users of a playbook do not mistakenly run the plays against their entire inventory (if the host is set to all). For example - ``hosts: '{{target|default("all")}}'``.
-To run the plays, users can now use such commands as ``ansible-playbook --e 'targets=webservers'`` or ``ansible-playbook --limit webservers``. Either way, the collection owner should document their playbooks and how to use them in the ``/docs`` folder or ``README`` file.
+To run the plays, users can now use such commands as ``ansible-playbook --e 'targets=webservers'`` or ``ansible-playbook --limit webservers``. Either way, the collection owner should document their playbooks and how to use them in the ``docs/`` folder or ``README`` file.
.. _developing_collections_tests_directory:
diff --git a/docs/docsite/rst/dev_guide/developing_python_3.rst b/docs/docsite/rst/dev_guide/developing_python_3.rst
index a58ee1ae35..74385c43f9 100644
--- a/docs/docsite/rst/dev_guide/developing_python_3.rst
+++ b/docs/docsite/rst/dev_guide/developing_python_3.rst
@@ -89,7 +89,7 @@ and while Python 2 is not a concern anymore we will continue to use them as they
dealing with unicode problematic.
While we will not be using it most of it anymore, the documentation below is still useful for those developing modules
-that still need to support both Python 2 and 3 simultaneouslly.
+that still need to support both Python 2 and 3 simultaneously.
Unicode Sandwich common borders: places to convert bytes to text in controller code
-----------------------------------------------------------------------------------
diff --git a/docs/docsite/rst/dev_guide/overview_architecture.rst b/docs/docsite/rst/dev_guide/overview_architecture.rst
index 2a3fe55bab..89677e96d9 100644
--- a/docs/docsite/rst/dev_guide/overview_architecture.rst
+++ b/docs/docsite/rst/dev_guide/overview_architecture.rst
@@ -53,7 +53,7 @@ Here's what a plain text inventory file looks like:
db0.example.com
db1.example.com
-Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/' or directly in the inventory file.
+Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/') or directly in the inventory file.
Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources like EC2, Rackspace, or OpenStack.
diff --git a/docs/docsite/rst/inventory/implicit_localhost.rst b/docs/docsite/rst/inventory/implicit_localhost.rst
index 2f065dc7b3..ced98df8e1 100644
--- a/docs/docsite/rst/inventory/implicit_localhost.rst
+++ b/docs/docsite/rst/inventory/implicit_localhost.rst
@@ -5,7 +5,9 @@
Implicit 'localhost'
====================
-When you try to reference a ``localhost`` and you don't have it defined in inventory, Ansible will create an implicit one for you.::
+When you try to reference a ``localhost`` and you don't have it defined in inventory, Ansible will create an implicit one for you.:
+
+.. code-block:: yaml
- hosts: all
tasks:
@@ -13,7 +15,9 @@ When you try to reference a ``localhost`` and you don't have it defined in inven
stat: path=/var/log/hosts/{{inventory_hostname}}.log
delegate_to: localhost
-In a case like this (or ``local_action``) when Ansible needs to contact a 'localhost' but you did not supply one, we create one for you. This host is defined with specific connection variables equivalent to this in an inventory::
+In a case like this (or ``local_action``) when Ansible needs to contact a 'localhost' but you did not supply one, we create one for you. This host is defined with specific connection variables equivalent to this in an inventory:
+
+.. code-block:: yaml
...
@@ -27,6 +31,7 @@ This ensures that the proper connection and Python are used to execute your task
You can override the built-in implicit version by creating a ``localhost`` host entry in your inventory. At that point, all implicit behaviors are ignored; the ``localhost`` in inventory is treated just like any other host. Group and host vars will apply, including connection vars, which includes the ``ansible_python_interpreter`` setting. This will also affect ``delegate_to: localhost`` and ``local_action``, the latter being an alias to the former.
.. note::
+
- This host is not targetable via any group, however it will use vars from ``host_vars`` and from the 'all' group.
- Implicit localhost does not appear in the ``hostvars`` magic variable unless demanded, such as by ``"{{ hostvars['localhost'] }}"``.
- The ``inventory_file`` and ``inventory_dir`` magic variables are not available for the implicit localhost as they are dependent on **each inventory host**.
diff --git a/docs/docsite/rst/network/getting_started/first_playbook.rst b/docs/docsite/rst/network/getting_started/first_playbook.rst
index b09814cd64..2c06ded742 100644
--- a/docs/docsite/rst/network/getting_started/first_playbook.rst
+++ b/docs/docsite/rst/network/getting_started/first_playbook.rst
@@ -95,7 +95,7 @@ The playbook contains one play with two tasks, and should generate output like t
$ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml
- PLAY [First Playbook]
+ PLAY [Network Getting Started First Playbook]
***************************************************************************************************************************
TASK [Get config for VyOS devices]
@@ -113,13 +113,13 @@ The playbook contains one play with two tasks, and should generate output like t
.. literalinclude:: sample_files/first_playbook_ext.yml
:language: YAML
-The extended first playbook has four tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:
+The extended first playbook has five tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:
.. code-block:: bash
$ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook_ext.yml
- PLAY [First Playbook]
+ PLAY [Network Getting Started First Playbook Extended]
************************************************************************************************************************************
TASK [Get config for VyOS devices]
diff --git a/docs/docsite/rst/network/user_guide/cli_parsing.rst b/docs/docsite/rst/network/user_guide/cli_parsing.rst
index 56121a443c..5b6b40ee1e 100644
--- a/docs/docsite/rst/network/user_guide/cli_parsing.rst
+++ b/docs/docsite/rst/network/user_guide/cli_parsing.rst
@@ -439,7 +439,7 @@ Parsing with textfsm
``textfsm`` is a Python module which implements a template-based state machine for parsing semi-formatted text.
-The following sample``textfsm`` template is stored as ``templates/nxos_show_interface.textfsm``
+The following sample ``textfsm`` template is stored as ``templates/nxos_show_interface.textfsm``
.. code-block:: text
diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst
index 90cdae1eb8..1b5a7d1bde 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst
@@ -2132,7 +2132,9 @@ To format a date using a string (like with the shell date command), use the "str
.. versionadded:: 2.13
-strftime takes an optional utc argument, defaulting to False, meaning times are in the local timezone::
+strftime takes an optional utc argument, defaulting to False, meaning times are in the local timezone:
+
+.. code-block:: yaml+jinja
{{ '%H:%M:%S' | strftime }} # time now in local timezone
{{ '%H:%M:%S' | strftime(utc=True) }} # time now in UTC
diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst
index 5d18b09393..e7196d2aaa 100644
--- a/docs/docsite/rst/reference_appendices/python_3_support.rst
+++ b/docs/docsite/rst/reference_appendices/python_3_support.rst
@@ -6,7 +6,7 @@ Ansible 2.5 and above work with Python 3. Previous to 2.5, using Python 3 was
considered a tech preview. This topic discusses how to set up your controller and managed machines
to use Python 3.
-.. note:: On the controller we support Python 3.5 or greater and Python 2.7 or greater. Module-side, we support Python 3.5 or greater and Python 2.6 or greater.
+See :ref: `Control Node Requirements <control_node_requirements>` and :ref: `Managed Node Requirements <managed_node_requirements>` for the specific versions supported.
On the controller side
----------------------
@@ -18,7 +18,7 @@ version of pip. This will make the default :command:`/usr/bin/ansible` run with
$ pip3 install ansible
$ ansible --version | grep "python version"
- python version = 3.6.2 (default, Sep 22 2017, 08:28:09) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]
+ python version = 3.10.5 (main, Jun 9 2022, 00:00:00) [GCC 12.1.1 20220507 (Red Hat 12.1.1-1)] (/usr/bin/python)
If you are running Ansible :ref:`from_source` and want to use Python 3 with your source checkout, run your
command through ``python3``. For example: