Package: aar-doc
aar-doc - Automated Ansible Role Documentationaar-docis a tool for generating documentation automatically from an Ansible role's metadata. Specifically, it reads themeta/main.ymlandmeta/argument_specs.ymlfiles.This is heavily inspired byterraform-docswhich does a similar thing with Terraform modules.aar-docisn't nearly as featureful though, but should do the trick!For instance, the only output format supported is Markdown. As withterraform-docs, you are able to override the default template however. As Ansible users are familiar withJinja2aar-docuses it for templating.Contributions are welcome to add support for more output formats!InstallationAsaar-docis a Python utility, the usualpip installworks, but the tool isn't (yet) published in Pypi. So you'll need to pointpipat the repository itself:pipinstallgit+https://gitlab.com/kankare/aar-docUsageUsage:aar-doc[OPTIONS]ROLE_PATHCOMMAND[ARGS]...AtoolforgeneratingdocsforAnsibleroles.

Arguments:ROLE_PATHPathtoanAnsiblerole[required]Options:--config-fileFILE[default:.aar-doc.yml]--output-fileFILE[default:README.md]--output-templateTEXTOutputtemplateasastringorapathtoafile.[default:<!--BEGIN_ANSIBLE_DOCS-->{{content}}<!--END_ANSIBLE_DOCS-->]--output-mode[inject|replace][default:inject]--install-completion[bash|zsh|fish|powershell|pwsh]Installcompletionforthespecifiedshell.--show-completion[bash|zsh|fish|powershell|pwsh]Showcompletionforthespecifiedshell,tocopyitorcustomizetheinstallation.--helpShowthismessageandexit.

Commands:markdownCommandforgeneratingroledocumentationinMarkdownformat.ModesTheinjectmode will inject only the changed content in between theBEGIN_ANSIBLE_DOCSandEND_ANSIBLE_DOCSmarkers. This makes it possible to have header and footer text in the file that is not touched. This is the default mode, and will revert toreplaceif the file does not exist to create it the first time.Thereplacemode will replace the whole file with the template. Usually, theinjectmode should be fine for regular usage and changing the mode is not necessary unless you want to overwrite an existing file.ConfigurationThe configuration options can be provided either via CLI arguments shown in--help, or a--config-filein YAML format. Note that the options have underscores when provided via the configuration file.Examples:aar-doc--output-fileROLE.md--output-modereplace...---output_file:ROLE.mdoutput_mode:replaceTemplatingYou can override the--output-templateused for rendering the document. This may be passed in as a string containing Jinja2, or a path to a file. As noted above, this option may be passed in via CLI or the configuration file.In the configuration file, easiest is to do a multiline string:---output_template:|<!-- BEGIN_ANSIBLE_DOCS -->This is my role: {{ role }}<!-- END_ANSIBLE_DOCS -->As noted above, the templatemuststart and end with the markers as comments, for the content injection to work.{{ content }}will contain the rendered builtin output specific template content. For Markdown, seetemplates/markdown.j2.You will most likely want to skip using it in your own template however, and use the provided variables containing therole metadataandargument specsdirectly.aar-docdoes not manipulate the values coming in from the YAML files in any way.Template variables:role: The role namecontent: Whole content as pre-rendered by the built in templatesmetadata: Metadata read frommeta/main.ymlargument_specs: Metadata read frommeta/argument_specs.ymlExample:<!-- BEGIN_ANSIBLE_DOCS -->

This is my role: {{ role }}

<!-- 'metadata' contains all the things in meta/main.yml -->
{{ metadata.galaxy_info.license }}

<!-- All the usual Jinja2 filters are available -->
{{ metadata.galaxy_info.galaxy_tags | sort }}

<!-- Including files is also possible in relation to the role's directory with Jinja2's include directive -->
{% include "defaults/main.yml" %}

<!-- 'argument_specs' contains all the things in meta/argument_specs.yml -->
{% for entrypoint, specs in argument_specs | items %}
Task file name: {{ entrypoint }}.yml has {{ specs | length }} input variables!
{% endfor %}
<!-- END_ANSIBLE_DOCS -->aar-doc--output-template./path/to/template.j2...More examples can be found in thetests.LicenseMITAknowledgementsKudos to the original authorMiika Kankare!Kudos toKevin P. Flemingfor his additions to the original project!