Skip to content

Helper scripts to generate documentation for role arguments in ansible collections

License

Notifications You must be signed in to change notification settings

adaemmer/collections-helper-scripts

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

10 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ansible collections doc helper scripts

Helper scripts to generate documentation for role arguments.

Installation

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.

Usage

vars2specs.py

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: ./].

specs2readme.py

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: ./].

License

Apache License v2.0 or later

See LICENSE to view the full text.

About

Helper scripts to generate documentation for role arguments in ansible collections

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%