From 45c8c9909de665e63a0c986bc96e4f99aac650f8 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 10 Sep 2020 11:48:28 -0400 Subject: [PATCH] [Docs][2.10] Backportapalooza 11 (#71702) * Add note on where inventory scripts moved to' (#71638) (cherry picked from commit 2f240f5dd7c6cc99c8c7eed57a58d7106a6fdda5) * clarify that collection names use same requirements as namespaces (#71639) (cherry picked from commit bbd4ec13f1a2ceba493054fa6e846d749d9a875e) * Fix typo in documentation (#71652) Fix typo on the page about unit testing modules, (cherry picked from commit 1ad0f666d5a1cc50413e6cbca222dfd53ebde9f1) * Changed all_modules references to list_of_collections in the documentation (#71656) (cherry picked from commit a34043c6be5e0bf6b58f19d28bf34fb774373a47) * Adds FAQ and other pointers for collections (#71606) (cherry picked from commit b430f9b9aa35bb8a2f38846535f4166d7e3f8ba2) * Docs(lineinfile): Update link to python regex docs (#71688) There was a link still pointing at the python2 documentation. (cherry picked from commit 11ba30183e40a3fb4dacb16b10e8ebdc0d956cf4) * Docsite: add reference to Style guide (#71694) (cherry picked from commit 73bed95ead697d0ac583654fc2475f1d7d4e13d1) Co-authored-by: Zois Pagoulatos 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 Co-authored-by: Andrew Klychkov --- docs/docsite/README.md | 6 ++-- .../rst/dev_guide/developing_collections.rst | 4 +-- .../developing_modules_documenting.rst | 4 ++- .../rst/dev_guide/developing_plugins.rst | 4 +-- .../rst/dev_guide/testing_units_modules.rst | 36 +++++++++---------- .../common_return_values.rst | 4 +-- docs/docsite/rst/reference_appendices/faq.rst | 17 +++++++++ .../reference_appendices/test_strategies.rst | 4 +-- .../docsite/rst/scenario_guides/guide_aws.rst | 4 +-- .../rst/user_guide/collections_using.rst | 2 +- docs/docsite/rst/user_guide/intro_adhoc.rst | 4 +-- .../user_guide/intro_dynamic_inventory.rst | 2 +- .../user_guide/playbooks_best_practices.rst | 4 +-- .../rst/user_guide/playbooks_intro.rst | 4 +-- .../user_guide/playbooks_reuse_includes.rst | 4 +-- .../rst/user_guide/playbooks_reuse_roles.rst | 4 +-- docs/docsite/rst/user_guide/sample_setup.rst | 4 +-- lib/ansible/modules/lineinfile.py | 2 +- 18 files changed, 66 insertions(+), 47 deletions(-) diff --git a/docs/docsite/README.md b/docs/docsite/README.md index 3c06d936d29..d643792e202 100644 --- a/docs/docsite/README.md +++ b/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/). diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index c812573a083..02f5a4823d8 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/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 `_ on the Galaxy docsite for details. + Both the namespace and collection names use the same strict set of requirements. See `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 `_ GitHub Org to get a better idea of what you can place inside a collection. @@ -784,7 +784,7 @@ If your collection is part of Ansible, use one of the following three options t * Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information. .. note:: - + For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release. .. seealso:: diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index ce196e5cfe5..6be4fcd0e7e 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/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 `. + 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 `, 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. diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index c698d037946..2a672848fb6 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/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` - List of all modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`developing_api` Learn about the Python API for task execution :ref:`developing_inventory` diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index 51bfa3f46a5..88763eb0a14 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -15,8 +15,8 @@ Introduction This document explains why, how and when you should use unit tests for Ansible modules. The document doesn't apply to other parts of Ansible for which the recommendations are -normally closer to the Python standard. There is basic documentation for Ansible unit -tests in the developer guide :ref:`testing_units`. This document should +normally closer to the Python standard. There is basic documentation for Ansible unit +tests in the developer guide :ref:`testing_units`. This document should be readable for a new Ansible module author. If you find it incomplete or confusing, please open a bug or ask for help on Ansible IRC. @@ -24,12 +24,12 @@ 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. Integration tests can be used for most modules, but there are situations where -cases cannot be verified using integration tests. This means that Ansible unit test cases +cases cannot be verified using integration tests. This means that Ansible unit test cases may extend beyond testing only minimal units and in some cases will include some level of functional testing. @@ -40,13 +40,13 @@ Why Use Unit Tests? Ansible unit tests have advantages and disadvantages. It is important to understand these. Advantages include: -* Most unit tests are much faster than most Ansible integration tests. The complete suite +* Most unit tests are much faster than most Ansible integration tests. The complete suite of unit tests can be run regularly by a developer on their local system. * Unit tests can be run by developers who don't have access to the system which the module is designed to work on, allowing a level of verification that changes to core functions haven't broken module expectations. * Unit tests can easily substitute system functions allowing testing of software that - would be impractical. For example, the ``sleep()`` function can be replaced and we check + would be impractical. For example, the ``sleep()`` function can be replaced and we check that a ten minute sleep was called without actually waiting ten minutes. * Unit tests are run on different Python versions. This allows us to ensure that the code behaves in the same way on different Python versions. @@ -62,7 +62,7 @@ implementation problem between the internal code tested and the actual result delivered to the user Normally the Ansible integration tests (which are written in Ansible YAML) provide better -testing for most module functionality. If those tests already test a feature and perform +testing for most module functionality. If those tests already test a feature and perform well there may be little point in providing a unit test covering the same area as well. When To Use Unit Tests @@ -85,13 +85,13 @@ Providing quick feedback Example: A single step of the rds_instance test cases can take up to 20 - minutes (the time to create an RDS instance in Amazon). The entire - test run can last for well over an hour. All 16 of the unit tests + minutes (the time to create an RDS instance in Amazon). The entire + test run can last for well over an hour. All 16 of the unit tests complete execution in less than 2 seconds. The time saving provided by being able to run the code in a unit test makes it worth creating a unit test when bug fixing a module, even if those tests do not often identify -problems later. As a basic goal, every module should have at least one unit test which +problems later. As a basic goal, every module should have at least one unit test which will give quick feedback in easy cases without having to wait for the integration tests to complete. @@ -110,9 +110,9 @@ Example: Another related use is in the situation where an API has versions which behave differently. A programmer working on a new version may change the module to work with the -new API version and unintentionally break the old version. A test case +new API version and unintentionally break the old version. A test case which checks that the call happens properly for the old version can help avoid the -problem. In this situation it is very important to include version numbering in the test case +problem. In this situation it is very important to include version numbering in the test case name (see `Naming unit tests`_ below). Providing specific design tests @@ -134,9 +134,9 @@ of the code, such as installing all of the packages supplied as arguments to the How to unit test Ansible modules ================================ -There are a number of techniques for unit testing modules. Beware that most +There are a number of techniques for unit testing modules. Beware that most modules without unit tests are structured in a way that makes testing quite difficult and -can lead to very complicated tests which need more work than the code. Effectively using unit +can lead to very complicated tests which need more work than the code. Effectively using unit tests may lead you to restructure your code. This is often a good thing and leads to better code overall. Good restructuring can make your code clearer and easier to understand. @@ -158,7 +158,7 @@ Use of Mocks Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very useful in building unit tests for special / difficult cases, but they can also -lead to complex and confusing coding situations. One good use for mocks would be in +lead to complex and confusing coding situations. One good use for mocks would be in simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use ``import units.compat.mock``). @@ -203,7 +203,7 @@ API definition with unit test cases ----------------------------------- API interaction is usually best tested with the function tests defined in Ansible's -integration testing section, which run against the actual API. There are several cases +integration testing section, which run against the actual API. There are several cases where the unit tests are likely to work better. Defining a module against an API specification @@ -214,7 +214,7 @@ an API that Ansible uses but which are beyond the control of the user. By writing a custom emulation of the calls that return data from the API, we can ensure that only the features which are clearly defined in the specification of the API are -present in the message. This means that we can check that we use the correct +present in the message. This means that we can check that we use the correct parameters and nothing else. @@ -522,7 +522,7 @@ Traps for maintaining Python 2 compatibility ============================================ If you use the ``mock`` library from the Python 2.6 standard library, a number of the -assert functions are missing but will return as if successful. This means that test cases should take great care *not* use +assert functions are missing but will return as if successful. This means that test cases should take great care *not* use functions marked as _new_ in the Python 3 documentation, since the tests will likely always succeed even if the code is broken when run on older versions of Python. diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index e24a30c418e..392dc96ce4a 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/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` - Learn about available modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins `GitHub modules directory `_ Browse source of core and extras modules `Mailing List `_ diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index d6d99eae4f3..329e2b4cdcf 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/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 `_. 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 `. Collections may be maintained by the Ansible team, by the Ansible community, or by Ansible partners. The `ansible/ansible repository `_ 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 `_ 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 `_ or ask on one of our :ref:`IRC channels `. .. _set_environment: diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index d41cdb69a29..01da667abe8 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -262,8 +262,8 @@ system. .. seealso:: - :ref:`all_modules` - All the documentation for Ansible modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`working_with_playbooks` An introduction to playbooks :ref:`playbooks_delegation` diff --git a/docs/docsite/rst/scenario_guides/guide_aws.rst b/docs/docsite/rst/scenario_guides/guide_aws.rst index 3a602aa1611..ba453195df3 100644 --- a/docs/docsite/rst/scenario_guides/guide_aws.rst +++ b/docs/docsite/rst/scenario_guides/guide_aws.rst @@ -269,8 +269,8 @@ documentation for a full list with examples. .. seealso:: - :ref:`all_modules` - All the documentation for Ansible modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`working_with_playbooks` An introduction to playbooks :ref:`playbooks_delegation` diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index 5aa616eac31..a9530a9e1d0 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/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 `_ +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 `. You can install and use collections through `Ansible Galaxy `_. diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst index 979126c403a..bf0b76581f4 100644 --- a/docs/docsite/rst/user_guide/intro_adhoc.rst +++ b/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` - A list of available modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`working_with_playbooks` Using Ansible for configuration management & deployment `Mailing List `_ diff --git a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst index aea7a0ca3e1..10b4b3d2c11 100644 --- a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst +++ b/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 `_. General usage is similar across all inventory scripts. You can also :ref:`write your own inventory script `. +In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are now in the `community.general scripts/inventory directory `_. We recommend you use :ref:`inventory_plugins` instead. .. _using_multiple_sources: diff --git a/docs/docsite/rst/user_guide/playbooks_best_practices.rst b/docs/docsite/rst/user_guide/playbooks_best_practices.rst index 775d390d469..86915f51fd9 100644 --- a/docs/docsite/rst/user_guide/playbooks_best_practices.rst +++ b/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` - Learn about available modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`developing_modules` Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index 56ac5a70eca..24037b3ed85 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -139,8 +139,8 @@ The `ansible-lint default rules `_ diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index e985ed46b91..90326ab79c9 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -466,8 +466,8 @@ Read the `Ansible Galaxy documentation `_ page Loops in playbooks :ref:`tags` Using tags to select or skip roles/tasks in long playbooks - :ref:`all_modules` - List of available modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`developing_modules` Extending Ansible by writing your own modules `GitHub Ansible examples `_ diff --git a/docs/docsite/rst/user_guide/sample_setup.rst b/docs/docsite/rst/user_guide/sample_setup.rst index ace2567e9ea..9be60004787 100644 --- a/docs/docsite/rst/user_guide/sample_setup.rst +++ b/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` - Learn about available modules + :ref:`list_of_collections` + Browse existing collections, modules, and plugins :ref:`developing_modules` Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` diff --git a/lib/ansible/modules/lineinfile.py b/lib/ansible/modules/lineinfile.py index d3bd1ca3454..4e856e50842 100644 --- a/lib/ansible/modules/lineinfile.py +++ b/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'