@ -52,11 +52,28 @@ A collection must have a ``galaxy.yml`` file that contains the necessary informa
.._collections_doc_dir:
docs directory
---------------
--------------
Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on.
For certified collections, Automation Hub displays documents written in markdown in the main ``docs`` directory with no subdirectories. This will not display on https://docs.ansible.com.
For community collections included in the Ansible PyPI package, docs.ansible.com displays documents written in reStructuredText (.rst) in a docsite/rst/ subdirectory. Define the structure of your extra documentation in ``docs/docsite/extra-docs.yml``:
..code-block:: yaml
---
sections:
- title: Scenario Guide
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>`_.
Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders.
Plugin and module documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use ``ansible-doc`` to view documentation for plugins inside a collection:
Keep the specific documentation for plugins and modules embedded as Python docstrings. Use ``ansible-doc`` to view documentation for plugins inside a collection: