# Ansible Documentation Template Extractor
**ansible-doc-template-extractor** is a documentation extractor for Ansible that
reads the documentation from spec files in YAML format and produces
documentation output using Jinja2 template files.
The supported formats of the spec files are:
* For Ansible roles, the Ansible-defined format in the
`<role>/meta/argument_specs.yml` files
(see [here](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format)).
* For Ansible playbooks, a format defined by this project (see below).
* You can also use any other spec file format for roles, playbooks or any other
Ansible items, as long as it is in YAML and you provide a custom template
for it.
The ansible-doc-template-extractor program includes a number of built-in
template files:
* role.rst.j2: Produces RST format from the Ansible-defined spec files for roles.
* role.md.j2: Produces Markdown format from the Ansible-defined spec files for roles.
* playbook.rst.j2: Produces RST format from the project-defined spec files for playbooks.
* playbook.md.j2: Produces Markdown format from the project-defined spec files for playbooks.
These templates are selected automatically based on the detected spec file type
and output format.
You can write your own custom templates for other output formats and/or
other spec file formats (see below).
Disclaimer: The ansible-doc-template-extractor tool should be seen as a
temporary bridge until there is official documentation extraction support for
Ansible roles and playbooks. There have been discussions in Ansible forums to
add support for Ansible roles to the ansible-doc and ansible-navigator tools.
Once that happens, the ansible-doc-template-extractor tool is probably no
longer needed for Ansible roles. In the event that an official spec format for
Ansible playbooks gets defined one day and that this format gets supported by
the ansible-doc and ansible-navigator tools, the ansible-doc-template-extractor
tool is probably no longer needed at all.
# Installation
If you want to install the package into a virtual Python environment:
```
$ pip install ansible-doc-template-extractor
```
Otherwise, you can also install it without depending on a virtual Python
environment:
- If not yet available, install the "pipx" command as described in
https://pipx.pypa.io/stable/installation/.
- Then, install the package using "pipx":
```
$ pipx install ansible-doc-template-extractor
```
# Example use
Suppose you have the following subtree:
```
├── my_collection
| ├── roles
| ├── my_role
| └── meta
| └── argument_specs.yml
├── docs
```
Then you can run the extractor as follows:
```
$ ansible-doc-template-extractor -v -o docs my_collection/roles/my_role/meta/argument_specs.yml
Loading template file: .../templates/role.rst.j2
Ansible spec type: role
Ansible name: my_role
Loading spec file: my_collection/roles/my_role/meta/argument_specs.yml
Created output file: docs/my_role.md
```
This will create an RST file with the documentation of the role:
```
├── docs
│ └── my_role.rst
```
Display the help message to learn about other options:
```
$ ansible-doc-template-extractor --help
```
# Format of spec file for Ansible playbooks
Note: This spec file format is preliminary at this point and can still change.
The spec file format defined by this project for Ansible playbooks:
```
playbook:
name: <Playbook name>
title: <Playbook title>
description:
<string or list of strings with playbook descriptions>
prerequisites:
<string or list of strings with playbook prerequisites>
version_added: <If the playbook was added to Ansible, the Ansible version>
examples:
- description: <string or list of strings with example description>
command: <example ansible-playbook command>
input_schema:
<A JSON schema that describes a single input variable of the playbook>
output_schema:
<A JSON schema that describes a single output variable for success>
authors:
- <list of strings with playbook author names>
```
An example spec file for playbooks using this format is in the
[examples/playbooks](https://github.com/andy-maier/ansible-doc-template-extractor/tree/main/examples/playbooks) directory.
# Writing custom templates
You can write your own custom templates for any other output format and/or for
any other spec file format.
The following rules apply when writing templates:
* The templating language is [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/).
* The following Jinja2 extensions are enabled for use by the template:
- The filters provided by the
[jinja2-ansible-filters](https://pypi.org/project/jinja2-ansible-filters)
package. For a description, see
[Ansible built-in filters](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html#filter-plugins).
- The [jinja2.ext.do Expression Statement](https://jinja.palletsprojects.com/en/stable/extensions/#expression-statement)
- The `to_rst` and `to_md` filters that are provided by the
ansible-doc-template-extractor package. They convert text to RST and
Markdown, respectively. They handle formatting and resolve Ansible-specific
constructs such as "C(...)".
* The following Jinja2 variables are set for use by the template:
- **name** (str): Name of the Ansible role, playbook, or other item.
- **spec_file_name** (str): Path name of the spec file.
- **spec_file_dict** (dict): Content of the spec file.
You can use the templates in the
[templates](https://github.com/andy-maier/ansible-doc-template-extractor/tree/main/src/ansible_doc_template_extractor/templates)
directory as examples for your own custom templates.
# Reporting issues
If you encounter a problem, please report it as an
[issue on GitHub](https://github.com/andy-maier/ansible-doc-template-extractor/issues).
# License
This package is licensed under the
[Apache 2.0 License](http://apache.org/licenses/LICENSE-2.0).
Raw data
{
"_id": null,
"home_page": null,
"name": "ansible-doc-template-extractor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Andreas Maier <andreas.r.maier@gmx.de>",
"keywords": "ansible, documentation, template",
"author": null,
"author_email": "Andreas Maier <andreas.r.maier@gmx.de>",
"download_url": "https://files.pythonhosted.org/packages/d9/7e/a332cc861cb5d973d386d30d19488d6c8327fd0c1361a63d9e2f8759fa83/ansible_doc_template_extractor-0.10.0.tar.gz",
"platform": "any",
"description": "# Ansible Documentation Template Extractor\n\n**ansible-doc-template-extractor** is a documentation extractor for Ansible that\nreads the documentation from spec files in YAML format and produces\ndocumentation output using Jinja2 template files.\n\nThe supported formats of the spec files are:\n* For Ansible roles, the Ansible-defined format in the\n `<role>/meta/argument_specs.yml` files\n (see [here](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format)).\n* For Ansible playbooks, a format defined by this project (see below).\n* You can also use any other spec file format for roles, playbooks or any other\n Ansible items, as long as it is in YAML and you provide a custom template\n for it.\n\nThe ansible-doc-template-extractor program includes a number of built-in\ntemplate files:\n\n* role.rst.j2: Produces RST format from the Ansible-defined spec files for roles.\n* role.md.j2: Produces Markdown format from the Ansible-defined spec files for roles.\n* playbook.rst.j2: Produces RST format from the project-defined spec files for playbooks.\n* playbook.md.j2: Produces Markdown format from the project-defined spec files for playbooks.\n\nThese templates are selected automatically based on the detected spec file type\nand output format.\n\nYou can write your own custom templates for other output formats and/or\nother spec file formats (see below).\n\nDisclaimer: The ansible-doc-template-extractor tool should be seen as a\ntemporary bridge until there is official documentation extraction support for\nAnsible roles and playbooks. There have been discussions in Ansible forums to\nadd support for Ansible roles to the ansible-doc and ansible-navigator tools.\nOnce that happens, the ansible-doc-template-extractor tool is probably no\nlonger needed for Ansible roles. In the event that an official spec format for\nAnsible playbooks gets defined one day and that this format gets supported by\nthe ansible-doc and ansible-navigator tools, the ansible-doc-template-extractor\ntool is probably no longer needed at all.\n\n# Installation\n\nIf you want to install the package into a virtual Python environment:\n\n```\n$ pip install ansible-doc-template-extractor\n```\n\nOtherwise, you can also install it without depending on a virtual Python\nenvironment:\n\n- If not yet available, install the \"pipx\" command as described in\n https://pipx.pypa.io/stable/installation/.\n\n- Then, install the package using \"pipx\":\n\n ```\n $ pipx install ansible-doc-template-extractor\n ```\n\n# Example use\n\nSuppose you have the following subtree:\n\n```\n\u251c\u2500\u2500 my_collection\n| \u251c\u2500\u2500 roles\n| \u00a0\u00a0 \u251c\u2500\u2500 my_role\n| \u00a0\u00a0 \u2514\u2500\u2500 meta\n| \u00a0\u00a0 \u2514\u2500\u2500 argument_specs.yml\n\u251c\u2500\u2500 docs\n```\n\nThen you can run the extractor as follows:\n\n```\n$ ansible-doc-template-extractor -v -o docs my_collection/roles/my_role/meta/argument_specs.yml\n\nLoading template file: .../templates/role.rst.j2\nAnsible spec type: role\nAnsible name: my_role\nLoading spec file: my_collection/roles/my_role/meta/argument_specs.yml\nCreated output file: docs/my_role.md\n```\n\nThis will create an RST file with the documentation of the role:\n\n```\n\u251c\u2500\u2500 docs\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 my_role.rst\n```\n\nDisplay the help message to learn about other options:\n\n```\n$ ansible-doc-template-extractor --help\n```\n\n# Format of spec file for Ansible playbooks\n\nNote: This spec file format is preliminary at this point and can still change.\n\nThe spec file format defined by this project for Ansible playbooks:\n\n```\nplaybook:\n name: <Playbook name>\n title: <Playbook title>\n description:\n <string or list of strings with playbook descriptions>\n prerequisites:\n <string or list of strings with playbook prerequisites>\n version_added: <If the playbook was added to Ansible, the Ansible version>\n examples:\n - description: <string or list of strings with example description>\n command: <example ansible-playbook command>\n input_schema:\n <A JSON schema that describes a single input variable of the playbook>\n output_schema:\n <A JSON schema that describes a single output variable for success>\n authors:\n - <list of strings with playbook author names>\n```\n\nAn example spec file for playbooks using this format is in the\n[examples/playbooks](https://github.com/andy-maier/ansible-doc-template-extractor/tree/main/examples/playbooks) directory.\n\n# Writing custom templates\n\nYou can write your own custom templates for any other output format and/or for\nany other spec file format.\n\nThe following rules apply when writing templates:\n\n* The templating language is [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/).\n\n* The following Jinja2 extensions are enabled for use by the template:\n\n - The filters provided by the\n [jinja2-ansible-filters](https://pypi.org/project/jinja2-ansible-filters)\n package. For a description, see\n [Ansible built-in filters](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html#filter-plugins).\n\n - The [jinja2.ext.do Expression Statement](https://jinja.palletsprojects.com/en/stable/extensions/#expression-statement)\n\n - The `to_rst` and `to_md` filters that are provided by the\n ansible-doc-template-extractor package. They convert text to RST and\n Markdown, respectively. They handle formatting and resolve Ansible-specific\n constructs such as \"C(...)\".\n\n* The following Jinja2 variables are set for use by the template:\n\n - **name** (str): Name of the Ansible role, playbook, or other item.\n\n - **spec_file_name** (str): Path name of the spec file.\n\n - **spec_file_dict** (dict): Content of the spec file.\n\nYou can use the templates in the\n[templates](https://github.com/andy-maier/ansible-doc-template-extractor/tree/main/src/ansible_doc_template_extractor/templates)\ndirectory as examples for your own custom templates.\n\n# Reporting issues\n\nIf you encounter a problem, please report it as an\n[issue on GitHub](https://github.com/andy-maier/ansible-doc-template-extractor/issues).\n\n# License\n\nThis package is licensed under the\n[Apache 2.0 License](http://apache.org/licenses/LICENSE-2.0).\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Ansible Documentation Template Extractor",
"version": "0.10.0",
"project_urls": {
"Bug Tracker": "https://github.com/andy-maier/ansible-doc-template-extractor/issues",
"Homepage": "https://github.com/andy-maier/ansible-doc-template-extractor",
"Source Code": "https://github.com/andy-maier/ansible-doc-template-extractor"
},
"split_keywords": [
"ansible",
" documentation",
" template"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f21a3136e640bcb3bd8060e9750767be41fd3b8f887ef198e644765c91f8cce0",
"md5": "38f4e4831b0d9746b1c8185ca83b7003",
"sha256": "6e8857e5fd3fd58c9d31ba1c2cab8b7632c205b2474b5200f35b1621bcf1de58"
},
"downloads": -1,
"filename": "ansible_doc_template_extractor-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38f4e4831b0d9746b1c8185ca83b7003",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18394,
"upload_time": "2025-11-02T16:40:14",
"upload_time_iso_8601": "2025-11-02T16:40:14.741139Z",
"url": "https://files.pythonhosted.org/packages/f2/1a/3136e640bcb3bd8060e9750767be41fd3b8f887ef198e644765c91f8cce0/ansible_doc_template_extractor-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d97ea332cc861cb5d973d386d30d19488d6c8327fd0c1361a63d9e2f8759fa83",
"md5": "1591f95483952235c82a7caf70ae8529",
"sha256": "a4cc6d606c1cafd567a8463be99f418d2dae871021a08ff8f20424e035b1b820"
},
"downloads": -1,
"filename": "ansible_doc_template_extractor-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "1591f95483952235c82a7caf70ae8529",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43127,
"upload_time": "2025-11-02T16:40:16",
"upload_time_iso_8601": "2025-11-02T16:40:16.295929Z",
"url": "https://files.pythonhosted.org/packages/d9/7e/a332cc861cb5d973d386d30d19488d6c8327fd0c1361a63d9e2f8759fa83/ansible_doc_template_extractor-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 16:40:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andy-maier",
"github_project": "ansible-doc-template-extractor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0.2"
]
]
},
{
"name": "jinja2-ansible-filters",
"specs": [
[
">=",
"1.3.1"
]
]
},
{
"name": "Jinja2",
"specs": [
[
">=",
"3.0.3"
]
]
},
{
"name": "antsibull-docs-parser",
"specs": [
[
">=",
"1.1.1"
]
]
}
],
"lcname": "ansible-doc-template-extractor"
}
JSON
