Skip to main content

Ansible-gendoc build documentation of Ansible Roles.

Project description

Ansible-Gendoc

Inspired by Felix Archambault's ansidoc project.

An example generated with ansible-gendoc.

Features

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

Quickstart

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

Run From docker

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 help

Install python package

Install the latest version ansible-gendoc with pip or pipx

pip install ansible-gendoc

Usage

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 README.md file.

ansible-gendoc init
ls templates
README.j2

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.10.tar.gz (13.9 kB view hashes)

Uploaded Source

Built Distribution

ansible_gendoc-0.1.10-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