Gendoc automatise la création de documentation Ansible

C'est avec joie que je vous annonce l'arrivée d'Ansible-Gendoc. Cet outil, python, permet de générer la documentation de vos roles automatiquement en s'appuyant sur un template Jinja et alimenté par le contenu des déclarations du rôle: default, vars et meta.

Installation d'ansible-gendoc

Le package est disponible sur Pypi.org.

Bien sûr, je vous conseille de l'installer dans un environnement virtuel :

python3 -m venv venv
. venv/bin/activate
pip install ansible-gendoc

Utilisation d'ansible gendoc

Obtenir de l'aide

Pour obtenir de l'aide sur cette commande comme souvent --help:

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                                                 │
╰──────────────────────────────────────────────────────────────────────────────────╯

Comme vous pouvez le constater pour le moment elle ne possède que deux options (pour le moment) :

• init
• render

Générer un template local

Init : optionnel puisque l'outil porte son propre template Jinja. Pour le générer localement afin de le modifier, il suffit d'invoquer cette commande suivie du chemin du rôle (si omis il utilisera le répertoire courant)

ansible-gendoc init [role_path]

Normalement dans le dossier templates vous devriez retrouver un fichier README.j2. Comme dis précédemment il utilise les templates Jinja. Si vous relancez la commande une seconde fois, ansible-gendoc refusera de l'écraser à moins d'ajouter --force à la commande init.

Générer la documentation

Render : pour obtenir de l'aide sur cette commande :

ansible-gendoc render --help

 Usage: ansible-gendoc render [OPTIONS] [PATH]

 Build the Documentation

╭─ Arguments ──────────────────────────────────────────────────────────────────────╮
│   path      [PATH]  The path of your role. [default: ./]                         │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────╮
│ --dry_run  -d        dry run, Outputs pure markdown to stdout nothing is written │
│                      to disk                                                     │
│ --verbose  -v        verbose mode                                                │
│ --help               Show this message and exit.                                 │
╰──────────────────────────────────────────────────────────────────────────────────╯

Lors de l'exécution de la commande render, si l'outil détecte la présence d'un d'un template templates/README.j2 dans le répertoire de votre role, il l'utilisera pour générer la documentation dur rôle.

Ajouter des sections au fichier README

Pour ajouter des sections à la page README, il suffit de créer des fichiers avec l'extension .md dans le répertoire racine du role. Ils seront automatiquement intégrés.

Documentation des variables du role

Bientôt disponible.

Les évolutions futures

Il manque quelques petites choses comme spécifier quels fichiers peuvent être intégré et dans quel ordre, des petites options. Vous pouvez me soumettre vos propositions sur le repository du projet github.com/claranet/ansible-gendoc. Vous pouvez aussi proposer des pull requests avec vos corrections ou ajouts.

Je dois aussi améliorer le CI, car il manque par exemple la création automatique des tags et releases lors des MERGE REQUEST.

Normalement, je vais continuer à travailler sur cet outil pour permettre de générer la documentation d'une collection Ansible. L'idée fournir une archive prête à être déployé sur un serveur http. Pour cela il s'appuiera soit sur Sphinx, soit sur Hugo. Ma préférence allant au second avec le thème Docsy gérant nativement le support des versions de la documentation.