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.

3

I found ansible-doctor to be simpler&more flexible a lot of the time.

I use it to do some neat tricks, such as:

  • document all vars by design - all things I expose to users must have some sane default in defaults/main.yml
  • I include the test playbook I run with molecule as an example of a workable playbook for the users. This means documentation is tested automatically, on each CI run :slight_smile:

That also helps keep me honest with how users interface with my roles.

The tool is nice, since it doesn’t force a format - it offers .md and hugo as example templates, but you can easily craft your own - it’s all just Jinja.

1 Like