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?

1 Like
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
4

Hi. I recently published DocSmith, which reads argument_specs.yml as the single source of truth and generates up‑to‑date documentation for:

  • README.md (or other .md/.rst files via custom templates)
  • Inline comments in defaults/main.yml (and other entry-points variable files)

It also validates that your defaults and argument specs stay in sync. DocSmith is available on PyPI (ansible-docsmith) and works well in CI/CD pipelines or pre‑commit hooks. It also support custom templates

Small example results generated from this argument_specs.yml:

Basic usage:

# Safely preview changes without writing to files. No modifications are made.
ansible-docsmith generate /path/to/role --dry-run

# Generate / update README.md and comments in entry-point files (like defaults/main.yml)
ansible-docsmith generate /path/to/role

# Show help
ansible-docsmith --help
ansible-docsmith generate --help

Validate argument_specs.yml and /defaults

# Validate argument_specs.yml structure as well as role entry-point files in /defaults/.
# These validation checks include:
#
# - ERROR:   Variables present in "defaults/" but missing from "argument_specs.yml".
# - ERROR:   Variables with "default:" values defined in "argument_specs.yml" but
#            missing from the entry-point files in "defaults/".
# - WARNING: Unknown keys in "argument_specs.yml".
# - NOTICE:  Potential mismatches, where variables are listed in "argument_specs.yml"
#            but not in "defaults/", for user awareness.
ansible-docsmith validate /path/to/role

# Show help
ansible-docsmith --help
ansible-docsmith validate --help

# Verbose output for debugging
ansible-docsmith validate /path/to/role --verbose

I built this because I was not satisfied with the existing tools (workflow, lack of validation outsidet the spec file itself and so on). Maybe DocSmith fits your needs, even if it just reached 1.0.0 :slight_smile:

2 Likes
5

This looks like a tool I needed, but I did not know it existed. Thank you!

6

I would like to give a shout-out to the DocSmith! This is a great tool already!

I did try it and it is great for role documentation generation and validation.
I especially love ‘validate’ command and option to use custom templates, which is not possible with community ansible tools.

1 Like