# Documenting roles **URL:** \ **Category:** Collection Development\ **Tags:** role, documentation\ **Created:** [May 16, 2025, 9:13am UTC](https://forum.ansible.com/t/documenting-roles/42700 "2025-05-16T09:13:37Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![andy-maier](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/andy-maier/32/7706_2.png) [@andy-maier](https://forum.ansible.com/u/andy-maier)\ **Post date:** [May 16, 2025, 9:13am UTC](https://forum.ansible.com/t/documenting-roles/42700/1 "2025-05-16T09:13:37Z")
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](https://pypi.org/project/docsible)) 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](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043) Is there a recommendation from the Ansible community on tools for creating .md or .rst documentation for roles? ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [May 16, 2025, 7:14pm UTC](https://forum.ansible.com/t/documenting-roles/42700/2 "2025-05-16T19:14:00Z")
If your roles are part of an Ansible collection, you can use [antsibull-docs](https://ansible.readthedocs.io/projects/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. ---
**Author:** ![danielpodwysocki](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/danielpodwysocki/32/7441_2.png) [@danielpodwysocki](https://forum.ansible.com/u/danielpodwysocki)\ **Post date:** [May 25, 2025, 5:59pm UTC](https://forum.ansible.com/t/documenting-roles/42700/3 "2025-05-25T17:59:35Z")
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 🙂 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. > **[GitHub - thegeeklab/ansible-doctor: Annotation based documentation for your Ansible...](https://github.com/thegeeklab/ansible-doctor)** > > Annotation based documentation for your Ansible roles ---
**Author:** ![andreashaerter](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/andreashaerter/32/9204_2.png) [@andreashaerter](https://forum.ansible.com/u/andreashaerter)\ **Post date:** [August 4, 2025, 8:18am UTC](https://forum.ansible.com/t/documenting-roles/42700/4 "2025-08-04T08:18:03Z")
> [@andy-maier](#): > > 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](https://pypi.org/project/docsible)) 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](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043) Hi. I recently published **[DocSmith](https://github.com/foundata/ansible-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`](https://github.com/foundata/ansible-collection-sshd/blob/main/roles/run/meta/argument_specs.yml):** - [Table and details of this `README.md`](https://github.com/foundata/ansible-collection-sshd/tree/main/roles/run#variables) - [All inline comment blocks in this `/defaults/main.yml`](https://github.com/foundata/ansible-collection-sshd/blob/main/roles/run/defaults/main.yml) **Basic usage:** ```bash # 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`** ```bash # 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 🙂 ---
**Author:** ![kks](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/kks/32/10352_2.png) [@kks](https://forum.ansible.com/u/kks)\ **Post date:** [August 7, 2025, 6:40pm UTC](https://forum.ansible.com/t/documenting-roles/42700/5 "2025-08-07T18:40:57Z")
This looks like a tool I needed, but I did not know it existed. Thank you! ---
**Author:** ![kks](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/kks/32/10352_2.png) [@kks](https://forum.ansible.com/u/kks)\ **Post date:** [August 9, 2025, 9:47am UTC](https://forum.ansible.com/t/documenting-roles/42700/6 "2025-08-09T09:47:12Z")
I would like to give a shout-out to the **[DocSmith](https://github.com/foundata/ansible-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.