diff options
author | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2021-06-03 13:22:21 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-06-03 14:22:21 -0400 |
commit | 605b1a1c5c3f551835a8228149df0f15e3c4d06d (patch) | |
tree | 3688b101b819b630aaf1bf6d9a24ad928cbd6584 /docs/docsite | |
parent | f88e81a62c49c4c89561a0bc5a3ebac6aa37d110 (diff) | |
download | ansible-605b1a1c5c3f551835a8228149df0f15e3c4d06d.tar.gz |
documents community 'extra docs' option in collections (#74886)
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Diffstat (limited to 'docs/docsite')
-rw-r--r-- | docs/docsite/rst/dev_guide/developing_collections_structure.rst | 23 |
1 files changed, 20 insertions, 3 deletions
diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 0a2f20a497..9682ab7398 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -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: .. code-block:: bash |