Generate documentation from annotated playbooks and roles using templates.
Note: this project is currently in Beta, issues, ideas and pull requests are welcome.
# install
pip install ansible-autodoc
# print help
ansible-autodoc -h
# print parsed annotation results in the cli
ansible-autodoc -p all path/to/role_or_playbook
# generate README file based on annotations
ansible-autodoc [path/to/project]
notes:
Use the following annotations in your playbooks and roles
# @meta author: Author Name
# @meta description: Project description
todo: use @todo to annotate improvements, bugs etc
# @todo bug: bug description
# @todo improvement: improvement
action: use @action to annotate a actions performed by the playbook/role
# @action install # this action describes the installation
# @action # this action does not have a section, only description
tags: use @tag to annotate tags, this is a special annotation as this will not only search for annotations, but also for used tags in the project and add that to the generated output.
# @tag tagname # tag description
variables: use @var this to annotate configuration variables
# @var my_var: default_value # description of the variable
example: the idea is that after every annotation, we can define an example block, linked to the annotation. in this case the example will be part of the var annotation.
# @var my_var: default_value # description of the variable
my_var: default_value
# @example # the hash is needed due to the parser constrains
# my_var:
# - subitem: string
# - subitem2: string
# @end
ansible-autodoc comes with 3 templates out of the box, the default is "readme", you can change this in configuration.
If you want to create your own project specific templates, see the template documentation
If a file already exists in the output, the you will be prompted to overwrite or abort.
The default "readme" template will generate a README.md file in the root of the project, detailing the sections:
you can extend this my creating a file "_readme_doby.md"
in the root of your project, this will be included in the rendered Readme just after the
initial description.
The "doc_and_readme" template is an extended template intended to be used playbook projects with several roles, it will generate a minimal README.md file and a documentation subfolder "doc" with more detailed information.
you can extend this my creating a file "_readme_doby.md"
in the root of your project, this will be included in the rendered Readme just after the
initial description.
the files created in the documentation folder will cover:
you can extend the documentation in this folder, just keep in mind that generated files will be overwritten.
The "cliprint" template is used to display the content when you use the command line print parameter "-p"
you can create a configuration file "autodoc.config.yaml" in the root of your project in order to modify several behaviours, see the sample config file for more details:
# role or project with playbooks
$ cd <project>
# create sample configuration (optional)
# you can pass the options as parameters too
$ ansible-autodoc --sample-doc > autodoc.config.yaml