Documentation tooling#

This project’s documentation is generated with:

  • Sphinx: the parser and documentation engine

  • MystParser: the Markdown plugin for Sphinx

  • Furo: The Sphinx theme

TODO: ref to how-to generate local static doc

Documenting Ansible roles#

The Ansible roles are documented from inside each role’s defaults/main.yml file.

Our documentation generation includes:

  • parse each role’s defaults/main.yml

  • remove the '# ' prefix on each commented line and treat it as Markdown

  • encapsulate every non-commented line within two line of triple backquote, aka: turn regular yaml into Markdown code blocks.

  • output the result in the doc/source/reference/role_<role name>.md

Not everything is automatic

Adding the output file into the menu structure is the contributor’s duty.

You can easily check on the result by comparing the source fo these two files:

  • roles/gitea/defaults/main.yml

  • doc/source/reference/role_gitea.md

Dear contributors…

Any open-source project is as good as its documentation. Like it or not, we will be judged by the cover of our book.