Documenting roles

Project Discussions Collection Development
,
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