[![](https://images.microbadger.com/badges/image/xoxys/ansible-doctor.svg)](https://microbadger.com/images/xoxys/ansible-doctor "Get your own image badge on microbadger.com")
This project is based on the idea (and at some parts on the code) of [ansible-autodoc](https://github.com/AndresBott/ansible-autodoc) by Andres Bott so credits goes to him for his work.
`ansible-doctor` is a simple annotation like documentation generator based on Jinja2 templates. While `ansible-doctor` comes with a default template called `readme`, it is also possible to write your own templates. This gives you the ability to customize the output and render the data to every format you like (e.g. html or xml).
`ansible-doctor` is designed to work within your CI pipeline to complete your testing and deployment workflow. Releases are available as Python Packages on [GitHub](https://github.com/xoxys/ansible-doctor/releases) or [PyPI](https://pypi.org/project/ansible-doctor/) and as Docker Image on [DockerHub](https://hub.docker.com/r/xoxys/ansible-doctor).
## Table of Content
* [Setup](#Setup)
* [Using pip](#Using-pip)
* [Using docker](#Using-docker)
* [Configuration](#Configuration)
* [Default settings](#Default-settings)
* [CLI options](#CLI-options)
* [Environment variables](#Environment-variables)
* [Usage](#Usage)
* [License](#License)
* [Maintainers and Contributors](#Maintainers-and-Contributors)
Generate documentation from annotated Ansible roles using templates
positional arguments:
role_dir role directory (default: current working dir)
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config CONFIG_FILE
location of configuration file
-o OUTPUT_DIR, --output OUTPUT_DIR
output base dir
-f, --force force overwrite output file
-d, --dry-run dry run without writing
-v increase log level
-q decrease log level
--version show program's version number and exit
```
#### Environment variables
```Shell
CONFIG_FILE=
ROLE_DIR=
DRY_RUN=false
LOG_LEVEL=warning
LOG_JSON=false
OUTPUT_DIR=
TEMPLATE_DIR=
TEMPLATE=readme
FORCE_OVERWRITE=false
CUSTOM_HEADER=
EXCLUDE_FILES=
# EXCLUDE_FILES=molecule/,files/**/*.py
```
### Usage
```Shell
ansible-doctor FOLDER
```
If you don't pass a folder to `ansible-doctor` your current working directory will be used. The first step is to identify if the given folder is an ansible role. This check is very simple, if the folder contains a subfolder called `tasks` is MUST be an ansible role! :)
After the successful check, `ansible-doctor` will try to read some static files into a dictionary:
* defaults/main.yml
* meta/main.yml
This will be the base result set which is used as data source for every output template. Without any work, you will get at least a documentation about available variables and some meta information. Theses basic information can be expanded with a set of available annotations. In general, an annotation is a comment with an identifier. This identifier is followed by colon separated options and ends with a value.