* Add note on where inventory scripts moved to' (#71638)
(cherry picked from commit 2f240f5dd7)
* clarify that collection names use same requirements as namespaces (#71639)
(cherry picked from commit bbd4ec13f1)
* Fix typo in documentation (#71652)
Fix typo on the page about unit testing modules,
(cherry picked from commit 1ad0f666d5)
* Changed all_modules references to list_of_collections in the documentation (#71656)
(cherry picked from commit a34043c6be)
* Adds FAQ and other pointers for collections (#71606)
(cherry picked from commit b430f9b9aa)
* Docs(lineinfile): Update link to python regex docs (#71688)
There was a link still pointing at the python2 documentation.
(cherry picked from commit 11ba30183e)
* Docsite: add reference to Style guide (#71694)
(cherry picked from commit 73bed95ead)
Co-authored-by: Zois Pagoulatos <zpagoulatos@hotmail.com>
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 <v.krasontov@gmail.com>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
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.
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).
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
Ansible style guide
===================
===================
@ -23,4 +23,4 @@ The Ansible community uses a range of tools and programs for working with Ansibl
GitHub
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/).
Both the namespace and collection names have strict requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#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 <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/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.
* 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::
..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.
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.
@ -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 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.
* 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 <style_guide>`.
Each documentation field is described below. Before committing your module documentation, please test it at the command line and as HTML:
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 <local_modules>`, 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.
* As long as your module file is :ref:`available locally <local_modules>`, 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:
: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,
* 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.
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.
* Unlike ``description:``, ``short_description`` should not have a trailing period/full stop.
Here are some commonly asked questions and their answers.
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 <https://www.ansible.com/blog/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 <list_of_collections>`. Collections may be maintained by the Ansible team, by the Ansible community, or by Ansible partners. The `ansible/ansible repository <https://github.com/ansible/ansible>`_ 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 <https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_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 <https://galaxy.ansible.com/>`_ or ask on one of our :ref:`IRC channels <communication_irc>`.
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 <https://docs.ansible.com/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 :ref:`collections pages <list_of_collections>`.
You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
@ -197,7 +197,7 @@ Note that the OpenStack dynamic inventory script will cache results to avoid rep
Other inventory scripts
Other inventory scripts
=======================
=======================
You can find all included inventory scripts in the `contrib/inventory directory <https://github.com/ansible/ansible/tree/stable-2.9/contrib/inventory>`_. General usage is similar across all inventory scripts. You can also :ref:`write your own inventory script <developing_inventory>`.
In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are now in the `community.general scripts/inventory directory <https://github.com/ansible-collections/community.general/tree/main/scripts/inventory>`_. We recommend you use :ref:`inventory_plugins` instead.
Sandra McCann
4 years ago
committed by