Docsible

About

Docsible is a command-line interface (CLI) written in Python that automates the documentation of Ansible roles and collections. It generates a Markdown-formatted README file for role or collection by scanning the Ansible YAML files.

Features
Installation
Usage
Data Sources
Prerequisites
Contributing
License

Features

Generates a README in Markdown format
Scans and includes default variables and role-specific variables
Parses tasks, including special Ansible task types like 'block' and 'rescue'
Optionally includes playbook content in the README
CLI-based, easy to integrate into a CI/CD pipeline
Provides a templating feature to customize output
Supports multiple YAML files within tasks, defaults, vars directory
Includes meta-data like author and license from meta/main.[yml/yaml]
Generates a well-structured table for default and role-specific variables
Support for encrypted Ansible Vault variables

Installation

How to create virtual env with python3

python3 -m venv docsible
source docsible/bin/activate

To install Docsible, you can run:

pip install docsible

Usage

To use Docsible, you can run the following command in your terminal:

Specific path

docsible --role /path/to/ansible/role --playbook /path/to/playbook.yml --graph

Document collection

docsible --collection ./collections_tests/lucian/ --no-backup --graph

Only role without playbook

docsible --role /path/to/ansible/role # without include a playbook into readme

$ docsible --help
Usage: docsible [OPTIONS]

Options:
  -r, --role TEXT                 Path to the Ansible role directory.
  -c, --collection TEXT           Path to the Ansible collection directory.
  -p, --playbook TEXT             Path to the playbook file.
  -g, --graph                     Generate Mermaid graph for tasks.
  -nob, --no-backup               Do not backup the readme before remove.
  -nod, --no-docsible             Do not generate .docsible file and do not include it in README.md.
  -com, --comments                Read comments from tasks files
  -ctpl, --md-collection-template TEXT Path to the collection markdown template file.
  -rtpl, -tpl, --md-role-template, --md-template TEXT
                                  Path to the role markdown template file.
  -a, --append                    Append to the existing README.md instead of
                                  replacing it.
  -o, --output TEXT               Output readme file name.
  -ru, --repository-url TEXT      Repository base URL (used for standalone roles)
  -rt, --repo-type TEXT           Repository type: github, gitlab, gitea, etc.
  -rb, --repo-branch TEXT         Repository branch name (e.g., main or master)
  --version                       Show the module version. Actual is 0.7.17
  --help                          Show this message and exit.

Flags

--role: Specifies the directory path to the Ansible role.
--collection: Specifies the directory path to the Ansible collection.
--playbook: Specifies the path to the Ansible playbook (Optional). (Works only with roles)
--graph: Generate mermaid for role and playbook.
--no-backup: Ignore existent README.md and remove before generate a new one. (Optional).
--no-docsible: Do not generate .docsible metadata file and exclude it from the README.md. (Optional).
--comments: Read comments from tasks files. (Optional).
--md-template: Specifies the path to the markdown template file (Optional). (Works only with roles)
--md-collection-template: Specifies the path to the markdown template file for documenting collections. (Optional).
--append: Append existing readme.md if needed.
--output: Output readme file name. Defaults to README.md.
--repository-url: Repository base URL (used for standalone roles). Use detect to auto-detect using Git, or provide a full URL.
--repo-type: Repository type: github, gitlab, gitea, etc. (Optional but needed if detect is not used with --repository-url).
--repo-branch: Repository branch name (e.g., main or master). (Optional but needed if detect is not used with --repository-url).
--version: Show the current module version and exit.
--help: Show this message and exit.

Data Sources

Docsible fetches information from the following files within the specified Ansible role:

defaults/*.yml/yaml: For default variables
vars/*.yml/yaml: For role-specific variables
meta/main.yml/yaml: For role metadata
tasks/*.yml/yaml: For tasks, including special task types and subfolders

Example

Thermo core simulator

Prerequisites

Docsible works with Python 3.x and requires the following libraries:

Click
Jinja2
PyYAML

TODO

Clean the code
Add more features
Multiple playbooks handle into mermaid for collection and role

About comments

This tool works with several types of comments.

On variables and defaults

The tool read comments placed before a variable, only if it begin with specific tag:

# title: This tag will be used to populate the column Title of README.md. It is a short description of the variable

# required: This tag will be used to populate the column Required of README.md.

# choices: This optional tag will be used to populate the column Choices of the README.md.

On tasks

The tool will read all the lines before each - name: of the tasks that begin with #. All comments will be reported to the column Comments of the tasks tables.

Contributing

For details on how to contribute, please read the Contributing Guidelines. Pull requests that do not follow the guidelines may be closed or require changes before being accepted.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Metadata

Release files for docsible 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for docsible 0.8.0
File	Size	Uploaded
docsible-0.8.0.tar.gz	21.5 kB	Nov 15, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for docsible 0.8.0
File	Interpreter	ABI	Platform	Reset
docsible-0.8.0-py3-none-any.whl 22.2 kB Nov 15, 2025	Python 3	none	any	Details

Total release size: 43.7 kB

Release files / docsible-0.8.0.tar.gz

Download URL	docsible-0.8.0.tar.gz
Size	21.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`cb9720505b3dc5352dff8fa4654211aacc81f862d2780b4ebcfd4e674278ff31`
BLAKE2b-256 checksum How to use checksums	`96ba8b62ce5128534079bd28de3624db3f4a92d85ac3cfa3cbab2c076517ce31`
Upload date	Nov 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.4 CPython/3.12.3 Linux/6.14.0-35-generic`

Release files / docsible-0.8.0-py3-none-any.whl

Download URL	docsible-0.8.0-py3-none-any.whl
Size	22.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1d7dce4e77a19f19b671798f2600adf2fa481c3afc8f1c28b0b69d127b477987`
BLAKE2b-256 checksum How to use checksums	`cb71761f81dac58d1e68b9e60f932ea2e20a0eb8bf50349fcfed98e5982952e7`
Upload date	Nov 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.4 CPython/3.12.3 Linux/6.14.0-35-generic`