Metadata-Version: 2.4
Name: ansible-doc-template-extractor
Version: 0.6.0
Summary: Ansible Documentation Template Extractor
Author-email: Andreas Maier <andreas.r.maier@gmx.de>
Maintainer-email: Andreas Maier <andreas.r.maier@gmx.de>
License: Apache License, Version 2.0
Project-URL: Homepage, https://github.com/andy-maier/ansible-doc-template-extractor
Project-URL: Bug Tracker, https://github.com/andy-maier/ansible-doc-template-extractor/issues
Project-URL: Source Code, https://github.com/andy-maier/ansible-doc-template-extractor
Keywords: ansible,documentation,template
Platform: any
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Systems Administration
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: jinja2-ansible-filters>=1.3.1
Requires-Dist: Jinja2>=3.0.3
Dynamic: license-file

# ansible-doc-template-extractor

**ansible-doc-template-extractor** is a documentation extractor that supports
the format Ansible roles use in their `meta/argument-spec.yml` files as input,
and arbitrary Jinja2 template files to control what is generated as output.

It can also be used for Ansible playbooks, as long as a spec file with a compatible
format to the Ansible roles spec files is provided.

The format of the ansible spec files for roles is described here:
https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format

Disclaimer: 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.
The ansible-doc-template-extractor tool should be seen as a temporary bridge
until there is more official documentation extraction support provided.

# Installation

With no virtual Python environment active:

```
$ pipx install ansible-doc-template-extractor
```

# Example use

Suppose you have the following subtree:

```
├── my_collection
|   ├── roles
|       ├── my_role
|           └── meta
|               └── argument_specs.yml
├── templates
│   └── role.md.j2
├── docs
```

Then you can run the extractor as follows:

```
$ ansible-doc-template-extractor --template templates/role.md.j2 docs my_collection/roles/my_role/meta/argument_specs.yml
Loading template file: templates/role.md.j2
Ansible name: my_role
Loading spec file: my_collection/roles/my_role/meta/argument_specs.yml
Created output file: docs/my_role.md
```

and it will create an .md file with the documentation of the role:

```
├── docs
│   └── my_role.md
```

Example template files can be downloaded from
https://github.com/andy-maier/ansible-doc-template-extractor/tree/master/examples/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).
