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 Markdownencapsulate 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.