ansible-autodoc 0.5.3

Description:

ansibleautodoc 0.5.3

ansible-autodoc

Generate documentation from annotated playbooks and roles using templates.
Note: this project is currently in Beta, issues, ideas and pull requests are welcome.

Features

allow to document playbook projects and roles
use templates to generate and maintain the documentation
extended functions when documenting:

tags: the autodoc will search for used tags in the project



Getting started
# 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:

you can use grip to see the live changes.
this only runs with python 3, if you still have python 2.x use pip3

Annotations
Use the following annotations in your playbooks and roles

meta: use @meta to annotate the metadata of playbook or role, like author
check below list of useful metadata

author: (self explanatory)
description: playbook / role description
name: to define a different role/project name instead of the folder name
license: (self explanatory)
email: (self explanatory)



# @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

Templates
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.
README
The default "readme" template will generate a README.md file in the root of the project, detailing the sections:

title and description
actions
tags
variables
todos
license
author infomration

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.
Doc and README
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:

tags: list all tags classified by roles
variables: list all variables classified by roles
todo: list all todo actions classified by roles
report: provides a report of the project and useful information during development

you can extend the documentation in this folder, just keep in mind that generated files will be overwritten.
Command line
The "cliprint" template is used to display the content when you use the command line print parameter "-p"
Configuration
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