A python package to automate documentation generation for ansible roles.
Project description
ansible-mdgen
Generate documentation for ansible roles
Description
This package reads all task files and creates equivalent .md files in the docs directory of the role. It also allows you to configure it so that you can combine tasks into a single .md file.
If docs directory does not exist then it will be created.
The script iterates over each of the tasks files, parsing the yaml to extract the "name" values from each task and writing it to the .md file. So good descriptions on the task names will lead to better documentation.
To install
pip install ansible-mdgen
To run
Call the python script passing in the path to the role
ansible-mdgen <path_to_role>
See --help for all available options
To configure
Create a configuration file called ansible-mdgen.yaml in the root of the project that you want to document. Alternatively rename the config file to something else and specify this in the command line using the -C or --conf options.
ansible-mdgen <path_to_role> --conf <name_of_config_file>
In the configuration file you can specify to combine various task files into a single md file for output e.g.
tasks:
combinations:
- filename: <name_of_single_file_to_create_1>
files_to_combine:
- name: <name_of_file_to_include_1>
- name: <name_of_file_to_include_2>
- name: <name_of_file_to_include_3>
- filename: <name_of_single_file_to_create_2>
files_to_combine:
- name: <name_of_file_to_include_1>
- name: <name_of_file_to_include_2>
e.g.
tasks:
combinations:
- filename: SystemSetup:
files_to_combine:
- name: install-packages.yml
- name: configure-services.yml
- name: start-services.yml
- filename: UserSetup:
files_to_combine:
- name: create-users.yml
- name: assign-privileges.yml
Combining tasks in a single .md file may be useful where related tasks have been broken down logically into different files but for documentation readability are better suited to being in one file.
To debug
Pass the options -vvv for debugging
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ansible_mdgen-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe7037e9c50eb741d444481b36c421b8f91768402cecb82ae1f4113abe9fec02 |
|
MD5 | fb77caae5538cbb56df45eaf158df4aa |
|
BLAKE2b-256 | 4699cfa4bdda1d88de0676270d2daf3215cb9f9fa25fc9356554e0dc72cd6c7d |