Metadata-Version: 2.1
Name: ansible-gendoc
Version: 0.1.9
Summary: Ansible-gendoc build documentation of Ansible Roles.
Home-page: https://www.claranet.fr/
Keywords: ansible,role,documentation
Author: Stephane ROBERT
Author-email: stephane.robert@fr.clara.net
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: GitPython (>=3.1.27,<4.0.0)
Requires-Dist: Jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: giturlparse (>=0.10.0,<0.11.0)
Requires-Dist: importlib-metadata (>=4.12.0,<5.0.0)
Requires-Dist: ruamel.yaml (>=0.17.21,<0.18.0)
Requires-Dist: typer[all] (>=0.6.1,<0.7.0)
Project-URL: Repository, https://github.com/claranet/ansible-gendoc
Description-Content-Type: text/markdown

# Ansible-Gendoc

*Inspired by Felix Archambault's* [ansidoc](https://github.com/archf/ansidoc)
project.

An [example](example.md) 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 :

```bash
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`

```bash
pip install ansible-gendoc
```

### Usage

```bash
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.

```bash
ansible-gendoc init
ls templates
README.j2
```

The template use [`jinja`](https://jinja.palletsprojects.com/) 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.

