Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/claranet/ansible-gendoc
Auto generate Ansible documentation
https://github.com/claranet/ansible-gendoc
ansible claranet sphinx
Last synced: about 2 months ago
JSON representation
Auto generate Ansible documentation
- Host: GitHub
- URL: https://github.com/claranet/ansible-gendoc
- Owner: claranet
- License: mpl-2.0
- Created: 2022-08-11T14:27:30.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-07T21:40:54.000Z (10 months ago)
- Last Synced: 2024-07-17T09:06:57.876Z (2 months ago)
- Topics: ansible, claranet, sphinx
- Language: Python
- Homepage:
- Size: 31.3 KB
- Stars: 25
- Watchers: 13
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# 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 :/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.