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.j2present in foldertemplates
If you have an existing README.md file in your role, backup it before !
Clone this project and build the image :
git clone
export DOCKER_BUILDKIT=1
docker build . -t ansible-gendoc:0.1.0 -t ansible-gendoc:latest
docker run --user $(id -u):$(id -g) -it ansible-gendoc:latest helpInstall the latest version ansible-gendoc with pip or pipx
pip install ansible-gendocansible-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 │
╰──────────────────────────────────────────────────────────────────────────────────╯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.
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 README.md file.
ansible-gendoc init
ls templates
README.j2The template use jinja as templating
language.
Modify it, for example replace html or Restructuredtext or another language.
You can remove some variables too.
The documentation of vars coming soon.