# DocSmith for Ansible: automating role documentation (using `argument_specs.yml`)
**This project is *not* associated with [Red Hat](https://www.redhat.com/) nor the [Ansible project](https://ansible.com/).** Please [report any bugs or suggestions to us](https://github.com/foundata/ansible-docsmith/blob/main/CONTRIBUTING.md), do NOT use the official Red Hat or Ansible support channels.
---
DocSmith is a documentation generator for Ansible roles. It reads a role's [`meta/argument_specs.yml`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format) and produces up‑to‑date variable descriptions for the `README.md` as well as inline comment blocks for `defaults/main.yml` (or other role entry-point files).
DocSmith works with roles in both [stand‑alone form](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html) and within [collections](https://docs.ansible.com/ansible/latest/collections_guide/index.html).
## Table of contents<a id="toc"></a>
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Preparations](#usage-preparations)
- [Generate or update documentation](#usage-generate)
- [Validate `argument_specs.yml` and `/defaults`](#usage-validate)
- [Custom templates](#usage-custom-templates)
- [Licensing, copyright](#licensing-copyright)
- [Author information](#author-information)
### Features<a id="features"></a>
- **Efficient and simple:** Uses the `argument_specs.yml` from [Ansible's built‑in role argument validation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-argument-validation) as the single source of truth, generating human‑readable documentation in multiple places while maintaining just one file.
- **Built-in validation:** Verifies that argument specs are complete, correct, and in sync with entry-point `defaults/`.
- **Automation‑friendly:** Works seamlessly in CI/CD pipelines and pre‑commit hooks.
## Installation<a id="installation"></a>
[](https://badge.fury.io/py/ansible-docsmith)
DocSmith needs Python ≥ v3.11. It is available on [PyPI](https://pypi.org/project/ansible-docsmith/) and can be installed with the package manager of your choice.
**Using [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended):**
```bash
uv tool install ansible-docsmith
```
**Using `pip` or `pipx`:**
```bash
pip install ansible-docsmith
pipx install ansible-docsmith
```
## Usage<a id="usage"></a>
### Preparations<a id="usage-preparations"></a>
1. If not already existing, simply **create an `argument_specs.yml`** for [Ansible’s role argument validation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-argument-validation). Try to add `description:` to your variables. The more complete your specification, the better the argument validation and documentation.
2. **Add simple markers in your role's `README.md`** where DocSmith shall maintain the human-readable documentation:
```
<!-- BEGIN ANSIBLE DOCSMITH -->
<!-- END ANSIBLE DOCSMITH -->
```
All content between these markers will be removed and updated on each `ansible-docsmith generate` run.
That's it. The entry-point variable files below the `/defaults` directory of your role do *not* need additional preparations. The tool will automatically (re)place formatted inline comment blocks above variables defined there.
### Generate or update documentation<a id="usage-generate"></a>
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
```
Advanced parameters:
```bash
# Generate / update only the README.md, skip comments for variables in
# entry-point files (like defaults/main.yml).
ansible-docsmith generate /path/to/role --no-defaults
# Generate / update only the comments in entry-point files (like defaults/main.yml),
# skip README.md
ansible-docsmith generate /path/to/role --no-readme
# Verbose output for debugging
ansible-docsmith generate /path/to/role --verbose
```
### Validate `argument_specs.yml` and `/defaults`<a id="usage-validate"></a>
```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
```
### Custom templates<a id="usage-custom-templates"></a>
You can customize the generated Markdown output by providing your own [Jinja2 template](https://jinja.palletsprojects.com/en/stable/templates/). The rendered content will be inserted between the `<!-- BEGIN ANSIBLE DOCSMITH -->` and `<!-- END ANSIBLE DOCSMITH -->` markers in the role’s `README.md` file.
```bash
# Use a custom template for README generation
ansible-docsmith generate /path/to/role --template-readme /path/to/custom-template.md.j2
# Combined with other options
ansible-docsmith generate /path/to/role --template-readme ./templates/my-readme.md.j2 --dry-run
```
Template files must use the `.j2` extension (for example, `simple-readme.md.j2`) and follow Jinja2 syntax. Below is a basic example:
```jinja2
# {{ role_name | title }} Ansible Role
{% if has_options %}
## Role variables
{% for var_name, var_spec in options.items() %}
- **{{ var_name }}** ({{ var_spec.type }}): {{ var_spec.description }}
{% endfor %}
{% else %}
The role has no configurable variables.
{% endif %}
```
**Check out the [`readme/default.md.j2`](https://github.com/foundata/ansible-docsmith/blob/main/ansibledocsmith/src/ansible_docsmith/templates/readme/default.md.j2)** template that DocSmith uses as an advanced example with conditional sections. Copying this file is often the easiest way to get started.
**Most important available template variables:**
- `role_name`: Name of the Ansible role.
- `has_options`: Boolean indicating if variables are defined.
- `options`: Dictionary of all role variables with their specifications.
- `entry_points`: List of all Ansible role entry-point names.
**Most important available Jinja2 filters:**
- `ansible_escape`: Escapes characters for Ansible/YAML contexts.
- `code_escape`: Escapes content for code blocks.
- `format_default`: Formats default values appropriately.
- `format_description`: Formats multi-line descriptions.
- `format_table_description`: Formats descriptions for table cells.
If you are creative, you may even maintain non-obvious parts of your `README.md` between the markers:
````jinja2
## Example Playbook
```yaml
[...]
- ansible.builtin.include_role:
name: "{{ role_name }}"
vars:
{% for var_name, var_spec in options.items() %}
{% if var_spec.default is not none %}
{{ var_name }}: {{ var_spec.default }}
{% else %}
# {{ var_name }}: # {{ var_spec.description }}
{% endif %}
{% endfor %}
```
## Author Information
{% if primary_spec.author %}
{% for author in primary_spec.author %}
- {{ author }}
{% endfor %}
{% endif %}
````
## Licensing, copyright<a id="licensing-copyright"></a>
<!--REUSE-IgnoreStart-->
Copyright (c) 2025 foundata GmbH (https://foundata.com)
This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: `GPL-3.0-or-later`), see [`LICENSES/GPL-3.0-or-later.txt`](LICENSES/GPL-3.0-or-later.txt) for the full text.
The [`REUSE.toml`](REUSE.toml) file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the [REUSE specification](https://reuse.software/spec/). You can use [`reuse spdx`](https://reuse.readthedocs.io/en/latest/readme.html#cli) to create a [SPDX software bill of materials (SBOM)](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange).
<!--REUSE-IgnoreEnd-->
[](https://api.reuse.software/info/github.com/foundata/ansible-docsmith)
## Author information<a id="author-information"></a>
This project was created and is maintained by [foundata](https://foundata.com/).
Raw data
{
"_id": null,
"home_page": null,
"name": "ansible-docsmith",
"maintainer": "Andreas Haerter",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Andreas Haerter <ah@foundata.com>",
"keywords": "ansible, documentation, yaml, cli, automation",
"author": "foundata GmbH, Andreas Haerter",
"author_email": "Andreas Haerter <ah@foundata.com>",
"download_url": "https://files.pythonhosted.org/packages/6e/5c/9630ec56d889db893504ebf7c5ee503cfab6812311cd02214e92011ae9e9/ansible_docsmith-1.0.0.tar.gz",
"platform": null,
"description": "# DocSmith for Ansible: automating role documentation (using `argument_specs.yml`)\n\n**This project is *not* associated with [Red Hat](https://www.redhat.com/) nor the [Ansible project](https://ansible.com/).** Please [report any bugs or suggestions to us](https://github.com/foundata/ansible-docsmith/blob/main/CONTRIBUTING.md), do NOT use the official Red Hat or Ansible support channels.\n\n---\n\nDocSmith is a documentation generator for Ansible roles. It reads a role's [`meta/argument_specs.yml`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format) and produces up\u2011to\u2011date variable descriptions for the `README.md` as well as inline comment blocks for `defaults/main.yml` (or other role entry-point files).\n\nDocSmith works with roles in both [stand\u2011alone form](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html) and within [collections](https://docs.ansible.com/ansible/latest/collections_guide/index.html).\n\n\n## Table of contents<a id=\"toc\"></a>\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Preparations](#usage-preparations)\n - [Generate or update documentation](#usage-generate)\n - [Validate `argument_specs.yml` and `/defaults`](#usage-validate)\n - [Custom templates](#usage-custom-templates)\n- [Licensing, copyright](#licensing-copyright)\n- [Author information](#author-information)\n\n\n### Features<a id=\"features\"></a>\n\n\n- **Efficient and simple:** Uses the `argument_specs.yml` from [Ansible's built\u2011in role argument validation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-argument-validation) as the single source of truth, generating human\u2011readable documentation in multiple places while maintaining just one file.\n- **Built-in validation:** Verifies that argument specs are complete, correct, and in sync with entry-point `defaults/`.\n- **Automation\u2011friendly:** Works seamlessly in CI/CD pipelines and pre\u2011commit hooks.\n\n\n## Installation<a id=\"installation\"></a>\n\n[](https://badge.fury.io/py/ansible-docsmith)\n\nDocSmith needs Python \u2265 v3.11. It is available on [PyPI](https://pypi.org/project/ansible-docsmith/) and can be installed with the package manager of your choice.\n\n**Using [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended):**\n\n```bash\nuv tool install ansible-docsmith\n```\n\n**Using `pip` or `pipx`:**\n\n```bash\npip install ansible-docsmith\npipx install ansible-docsmith\n```\n\n\n## Usage<a id=\"usage\"></a>\n\n### Preparations<a id=\"usage-preparations\"></a>\n\n1. If not already existing, simply **create an `argument_specs.yml`** for [Ansible\u2019s role argument validation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-argument-validation). Try to add `description:` to your variables. The more complete your specification, the better the argument validation and documentation.\n2. **Add simple markers in your role's `README.md`** where DocSmith shall maintain the human-readable documentation:\n ```\n <!-- BEGIN ANSIBLE DOCSMITH -->\n <!-- END ANSIBLE DOCSMITH -->\n ```\n All content between these markers will be removed and updated on each `ansible-docsmith generate` run.\n\nThat's it. The entry-point variable files below the `/defaults` directory of your role do *not* need additional preparations. The tool will automatically (re)place formatted inline comment blocks above variables defined there.\n\n\n### Generate or update documentation<a id=\"usage-generate\"></a>\n\nBasic usage:\n\n```bash\n# Safely preview changes without writing to files. No modifications are made.\nansible-docsmith generate /path/to/role --dry-run\n\n# Generate / update README.md and comments in entry-point files (like defaults/main.yml)\nansible-docsmith generate /path/to/role\n\n# Show help\nansible-docsmith --help\nansible-docsmith generate --help\n```\n\nAdvanced parameters:\n\n```bash\n# Generate / update only the README.md, skip comments for variables in\n# entry-point files (like defaults/main.yml).\nansible-docsmith generate /path/to/role --no-defaults\n\n# Generate / update only the comments in entry-point files (like defaults/main.yml),\n# skip README.md\nansible-docsmith generate /path/to/role --no-readme\n\n# Verbose output for debugging\nansible-docsmith generate /path/to/role --verbose\n```\n\n\n### Validate `argument_specs.yml` and `/defaults`<a id=\"usage-validate\"></a>\n\n```bash\n# Validate argument_specs.yml structure as well as role entry-point files in /defaults/.\n# These validation checks include:\n#\n# - ERROR: Variables present in \"defaults/\" but missing from \"argument_specs.yml\".\n# - ERROR: Variables with \"default:\" values defined in \"argument_specs.yml\" but\n# missing from the entry-point files in \"defaults/\".\n# - WARNING: Unknown keys in \"argument_specs.yml\".\n# - NOTICE: Potential mismatches, where variables are listed in \"argument_specs.yml\"\n# but not in \"defaults/\", for user awareness.\nansible-docsmith validate /path/to/role\n\n# Show help\nansible-docsmith --help\nansible-docsmith validate --help\n\n# Verbose output for debugging\nansible-docsmith validate /path/to/role --verbose\n```\n\n\n### Custom templates<a id=\"usage-custom-templates\"></a>\n\nYou can customize the generated Markdown output by providing your own [Jinja2 template](https://jinja.palletsprojects.com/en/stable/templates/). The rendered content will be inserted between the `<!-- BEGIN ANSIBLE DOCSMITH -->` and `<!-- END ANSIBLE DOCSMITH -->` markers in the role\u2019s `README.md` file.\n\n```bash\n# Use a custom template for README generation\nansible-docsmith generate /path/to/role --template-readme /path/to/custom-template.md.j2\n\n# Combined with other options\nansible-docsmith generate /path/to/role --template-readme ./templates/my-readme.md.j2 --dry-run\n```\n\nTemplate files must use the `.j2` extension (for example, `simple-readme.md.j2`) and follow Jinja2 syntax. Below is a basic example:\n\n```jinja2\n# {{ role_name | title }} Ansible Role\n\n{% if has_options %}\n## Role variables\n\n{% for var_name, var_spec in options.items() %}\n- **{{ var_name }}** ({{ var_spec.type }}): {{ var_spec.description }}\n{% endfor %}\n{% else %}\nThe role has no configurable variables.\n{% endif %}\n```\n\n**Check out the [`readme/default.md.j2`](https://github.com/foundata/ansible-docsmith/blob/main/ansibledocsmith/src/ansible_docsmith/templates/readme/default.md.j2)** template that DocSmith uses as an advanced example with conditional sections. Copying this file is often the easiest way to get started.\n\n**Most important available template variables:**\n- `role_name`: Name of the Ansible role.\n- `has_options`: Boolean indicating if variables are defined.\n- `options`: Dictionary of all role variables with their specifications.\n- `entry_points`: List of all Ansible role entry-point names.\n\n**Most important available Jinja2 filters:**\n- `ansible_escape`: Escapes characters for Ansible/YAML contexts.\n- `code_escape`: Escapes content for code blocks.\n- `format_default`: Formats default values appropriately.\n- `format_description`: Formats multi-line descriptions.\n- `format_table_description`: Formats descriptions for table cells.\n\nIf you are creative, you may even maintain non-obvious parts of your `README.md` between the markers:\n\n````jinja2\n## Example Playbook\n\n```yaml\n[...]\n- ansible.builtin.include_role:\n name: \"{{ role_name }}\"\n vars:\n{% for var_name, var_spec in options.items() %}\n{% if var_spec.default is not none %}\n {{ var_name }}: {{ var_spec.default }}\n{% else %}\n # {{ var_name }}: # {{ var_spec.description }}\n{% endif %}\n{% endfor %}\n```\n\n## Author Information\n\n{% if primary_spec.author %}\n{% for author in primary_spec.author %}\n\n- {{ author }}\n{% endfor %}\n{% endif %}\n````\n\n\n## Licensing, copyright<a id=\"licensing-copyright\"></a>\n\n<!--REUSE-IgnoreStart-->\nCopyright (c) 2025 foundata GmbH (https://foundata.com)\n\nThis project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: `GPL-3.0-or-later`), see [`LICENSES/GPL-3.0-or-later.txt`](LICENSES/GPL-3.0-or-later.txt) for the full text.\n\nThe [`REUSE.toml`](REUSE.toml) file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the [REUSE specification](https://reuse.software/spec/). You can use [`reuse spdx`](https://reuse.readthedocs.io/en/latest/readme.html#cli) to create a [SPDX software bill of materials (SBOM)](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange).\n<!--REUSE-IgnoreEnd-->\n\n[](https://api.reuse.software/info/github.com/foundata/ansible-docsmith)\n\n\n## Author information<a id=\"author-information\"></a>\n\nThis project was created and is maintained by [foundata](https://foundata.com/).\n",
"bugtrack_url": null,
"license": null,
"summary": "DocSmith for Ansible: automating role documentation (using argument_specs.yml)",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/foundata/ansible-docsmith/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/foundata/ansible-docsmith?tab=readme-ov-file",
"Homepage": "https://github.com/foundata/ansible-docsmith",
"Issues": "https://github.com/foundata/ansible-docsmith/issues",
"Repository": "https://github.com/foundata/ansible-docsmith.git"
},
"split_keywords": [
"ansible",
" documentation",
" yaml",
" cli",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e0cf83dd886834278e7f34e3dc51abd483269d4bf98ba2d8a8b3a40c55179efa",
"md5": "e3bd034a4764ba787826727329604895",
"sha256": "37651afed16b47ee805ed7980119d4ebe8dff35f97ee62d5efdc26a7541fd386"
},
"downloads": -1,
"filename": "ansible_docsmith-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3bd034a4764ba787826727329604895",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 37087,
"upload_time": "2025-08-04T02:25:39",
"upload_time_iso_8601": "2025-08-04T02:25:39.178669Z",
"url": "https://files.pythonhosted.org/packages/e0/cf/83dd886834278e7f34e3dc51abd483269d4bf98ba2d8a8b3a40c55179efa/ansible_docsmith-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6e5c9630ec56d889db893504ebf7c5ee503cfab6812311cd02214e92011ae9e9",
"md5": "417752d2b13c9301b17b13da8a93a035",
"sha256": "c98c0e357a13fd513d561191ad3180776a0377305217a3a6911151279cda7c3a"
},
"downloads": -1,
"filename": "ansible_docsmith-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "417752d2b13c9301b17b13da8a93a035",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 34016,
"upload_time": "2025-08-04T02:25:40",
"upload_time_iso_8601": "2025-08-04T02:25:40.797410Z",
"url": "https://files.pythonhosted.org/packages/6e/5c/9630ec56d889db893504ebf7c5ee503cfab6812311cd02214e92011ae9e9/ansible_docsmith-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 02:25:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "foundata",
"github_project": "ansible-docsmith",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ansible-docsmith"
}
JSON
