Package: ansible-autodoc
ansible-autodocGenerate documentation from annotated playbooks and roles using templates.Note: this project is currently in Beta, issues, ideas and pull requests are welcome.Featuresallow to document playbook projects and rolesuse templates to generate and maintain the documentationextended functions when documenting:tags: the autodoc will search for used tags in the projectGetting 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 usegripto see the live changes.this only runs with python 3, if you still have python 2.x use pip3AnnotationsUse the following annotations in your playbooks and rolesmeta:use @meta to annotate the metadata of playbook or role, like author
check below list of useful metadataauthor: (self explanatory)description: playbook / role descriptionname: to define a different role/project name instead of the folder namelicense: (self explanatory)email: (self explanatory)# @meta author: Author Name# @meta description: Project descriptiontodo:use @todo to annotate improvements, bugs etc# @todo bug: bug description# @todo improvement: improvementaction: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 descriptiontags: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 descriptionvariables:use @var this to annotate configuration variables# @var my_var: default_value # description of the variableexample: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 variablemy_var:default_value# @example # the hash is needed due to the parser constrains# my_var:#  - subitem: string#  - subitem2: string# @endTemplatesansible-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 thetemplate documentationIf a file already exists in the output, the you will be prompted to overwrite or abort.READMEThe default "readme" template will generate a README.md file in the root of the project, detailing the sections:title and descriptionactionstagsvariablestodoslicenseauthor infomrationyou 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 READMEThe "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 rolesvariables: list all variables classified by rolestodo: list all todo actions classified by rolesreport: provides a report of the project and useful information during developmentyou can extend the documentation in this folder, just keep in mind that generated files will be overwritten.Command lineThe "cliprint" template is used to display the content when you use the command line print parameter "-p"Configurationyou 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