Develop template/guidance for use of collection /docs/ folder

[acozine]

We currently publish documentation for modules and some other plugins from collections. Each collection could include much more documentation, such as examples and guides for using the various modules and other elements of the collection together. For example, the content currently hosted as Scenario Guides in ansible/ansible should be hosted in the relevant collections.

The /docs/ folder in the collection template is an excellent place to host this extended documentation, but we do not currently have a mechanism for publishing anything from that folder, or any guidance for collection owners on how to use the folder. Documentation from each collection's /docs/ folder may someday be available on Galaxy, but currently it is not, and the plan does not include any kind of cross-linking for those docs. We may be able to handle these documents on docs.ansible.com. Let's discuss the possibilities here.

At the DaWGs meeting on January 12, 2021 full meeting log we started a conversation. Please join the discussion by adding comments, links, ideas, objections, suggestions, and questions below.

Option A was decided on at the March 23 DaWGs meeting.

Option A: Add to the existing docs pipeline

• To publish content from collections /docs/ folders to docs.ansible.com, we need to validate/test this content.
• To manage the inevitable breakages (for example, conflicting labels within a collection's /docs/ folder), we need a way to either exclude content that fails validation or maintain a list of known-good collections to include.
• To allow collection owners to "do their own thing" in the /docs/ folder, we need to allow collection owners to opt out of publishing to docs.ansible.com, possibly by applying any rules only to a sub-folder?
• To support cross-references, we need to apply unique labels to collections-based pages.
  • Adding this in the pipeline would be harder than validating content added to the rst files.
  • Can we use rstcheck to validate that each page has a unique label that begins with the collection namespace and name?
  • Potential pattern for labels in the collection /docs/ folder: .. _anscoll_<namespace>_<collection>_<page>::

Pros of Option A

• Keeps publication logic, testing, validation centralized.
• Integrates navigation from one collection to another and/or from collections to other documentation.

Cons of Option A

• High overhead/responsibility for docs and community teams.

Option B: Require collection owners to publish their own docsites

• Here's an existing example: https://docs.steampunk.si/unit/.
• How would we integrate these into the rest of docs.ansible.com?
  • Per tadeboro, add Sphinx config and other magic so that the collection authors only need to provide the text.
  • Works best with a drop-in AnsibleDocs sphinx theme.
  • Requires a spec, including at minimum a top-level index.rst file.
  • Would the boundaries be visible to users?
  • What would the TOC/left-hand nav look like?
• Would this risk collection owners dropping module documentation (by mistake or on purpose)?

Pros of Option B

• Makes collection owners responsible for their own documentation.
• Provides clarity for users on who owns which collections.

Cons of Option B

• Might be hard for users to navigate.
• Might not support module index pages except at the collection level.

[acozine]

Proposed PR with sample collection #255.

[samccann]

Documented at https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#collections-doc-dir on how to do this.