Helper scripts to generate documentation for role arguments.
Install dependencies:
pip install -r requirements.txt
Then:
python <script.py> [-c] [--role_dir=<role_dir>]
The scripts will generate meta/argument_specs.yml for each new parsed variable; and using argument_specs.yml, can generate README.md tabular documentation.
Scripts were tested with python 3.9+
If you are looking for ansible-lint rules to check argument_specs.yml against var-files, see our custom rules.
Parses role default/main.yml and varrs/main.yml and for each unspecified arguments creates elements in argument_specs.yml
Generates argument_specs.yml from variables parsed in role.
Usage:
vars2specs.py [-c] [-r DIR]
Options:
-c Parse all roles in a collection [default: no]
-r DIR --role_dir=DIR Input role directory [default: ./].
The script will look for the following placeholder in README.md:
<!--start argument_specs-->
[...]
<!--end argument_specs-->
and add any undefined variable or default reading the specification in meta/argument_specs.yml under the following headings:
Role Variables
--------------
| Variable | Description |
|:---------|:------------|
>> required variables will be added here
|`i_am_required`| give value to me |
** other already listed variables will be left untouched
Role Defaults
-------------
| Variable | Description | Default |
|:---------|:------------|:--------|
>> defaults with be added here
|`know_what_you_doing`| override if needed | `false` |
** other already listed default will be left untouched
Usage:
Generates README.md docs from argument_specs.yml.
Usage:
specs2readme.py [-c] [-r DIR]
Options:
-c Parse all roles in a collection [default: no]
-r DIR --role_dir=DIR Input role directory [default: ./].
Apache License v2.0 or later
See LICENSE to view the full text.