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.
tasks, defaults, vars directorymeta/main.[yml/yaml]How to create virtual env with python3
python3 -m venv docsible
source docsible/bin/activate
To install Docsible, you can run:
pip install docsible
To use Docsible, you can run the following command in your terminal:
docsible --role /path/to/ansible/role --playbook /path/to/playbook.yml --graph
docsible --collection ./collections_tests/lucian/ --no-backup --graph
docsible --role /path/to/ansible/role # without include a playbook into readme
$ docsible --help
Usage: docsible [OPTIONS]
Options:
--role TEXT Path to the Ansible role directory.
--collection TEXT Path to the Ansible collection directory.
--playbook TEXT Path to the playbook file.
--graph Generate Mermaid graph for tasks.
--no-backup Do not backup the readme before remove.
--no-docsible Do not create .docsible file and do not print relative variable to generated README.md.
--comments Read comments from tasks files.
--md-template Path to the markdown template file.
--append Append to the existing README.md instead of replacing it.
--version Show the module version.
--help Show this message and exit.
--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).--comments: Read comments from tasks files. (Optional).--md-template: Specifies the path to the markdown template file (Optional). ( Works only with roles )--append: Append existing readme.md if neededDocsible fetches information from the following files within the specified Ansible role:
defaults/*.yml/yaml: For default variablesvars/*.yml/yaml: For role-specific variablesmeta/main.yml/yaml: For role metadatatasks/*.yml/yaml: For tasks, including special task types and subfoldersDocsible works with Python 3.x and requires the following libraries:
This tool work whith several type of comments.
The tool read comments placed before a variable, only if it begin with specific tag:
# title: This tag will be used for popiulate the column Title of the README.md. It is a short description of the variable
# required: This tag will be used for popiulate the column Required of the README.md
# choices: This optional tag will be used for popiulate the column Choices of the README.md
The tool will read all the line before each - name: of the tasks that begin with #.
All comment will be reported to the column Comments of the tasks tables.
For details on how to contribute, please read the Contributing Guidelines.
This project is licensed under the MIT License. See the LICENSE file for more details.
FAQs
Document generator for ansible role/collection
We found that docsible demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.