Skip to main content

Ansible-gendoc build documentation of Ansible Roles.

Project description


Inspired by Felix Archambault's ansidoc project.

An example generated with ansible-gendoc.


  • Generate the documentation for a role located in a directory
  • Can use a personal template README.j2 present in folder templates


If you have an existing file in your role, backup it before !

Run From docker

Clone this project and build the image :

git clone
docker build . -t ansible-gendoc:0.1.0 -t ansible-gendoc:latest
docker run --user $(id -u):$(id -g) -it ansible-gendoc:latest help

Install python package

Install the latest version ansible-gendoc with pip or pipx

pip install ansible-gendoc


ansible-gendoc --help

 Usage: ansible-gendoc [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────╮
│ --version             -v        Show the application's version and exit.         │
│ --install-completion            Install completion for the current shell.        │
│ --show-completion               Show completion for the current shell, to copy   │
│                                 it or customize the installation.                │
│ --help                          Show this message and exit.                      │
╭─ Commands ───────────────────────────────────────────────────────────────────────╮
│ init     Copy templates README.j2 from packages in templates/role folder.        │
│ render   Build the Documentation                                                 │

Build your first documentation of a role

To build the documentation roles, you can run these commands :

  • with package installed with pip ansible-gendoc render.
  • with docker images docker run --user $(id -u):$(id -g) -v <path_role>:/role -it ansible-gendoc:latest render role.

Use your personal template

To use a personal template, you need to init the template in the templates folder of your role. If ansible-gendoc find an existing file templates/README.j2, it will use it to render the file.

ansible-gendoc init
ls templates

The template use jinja as templating language.

Modify it, for example replace html or Restructuredtext or another language. You can remove some variables too.

Documentation of vars template

The documentation of vars coming soon.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible-gendoc-0.1.11.tar.gz (14.0 kB view hashes)

Uploaded Source

Built Distribution

ansible_gendoc-0.1.11-py3-none-any.whl (19.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page