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>

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