Documenting roles

Project Discussions Collection Development
,
1

I am trying to document our Ansible roles and to generate .md or .rst files from them.

The Ansible docs recommend documenting roles in meta/argument_specs.yml, but they are silent about how an .md or .rst file can be generated from that.

I found docsible (Client Challenge) and it seems to be able to parse the meta/argument_specs.yml files. I also read Lucian’s thread here: Easy documentation for roles/collection

Is there a recommendation from the Ansible community on tools for creating .md or .rst documentation for roles?

2

If your roles are part of an Ansible collection, you can use antsibull-docs to generate RST files (for processing with Sphinx, for example). It won’t work for standalone roles, though, and right now it has no MarkDown support.