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 a role or collection by scanning the Ansible YAML files.

Project home: https://github.com/docsible/docsible

Table of Contents

• Features
• Installation
• Quick Start
• Command Reference
  • docsible init
  • docsible document role
  • docsible analyze role
  • docsible validate role
  • docsible suppress
  • docsible guide
  • docsible role (legacy)
• Presets
• Suppression System
• Hybrid Template
• Data Sources
• Comment Tags
• 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 directories
• Includes metadata 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
• Flexible project structure support (AWX, monorepos, custom directories)
• Auto-detection of various Ansible project layouts
• Optional .docsible/config.yml configuration for custom structures and presets
• Comment tag flexibility (supports both - and _ separators)
• Intelligent caching system (4-100x faster on repeated runs)
• Modular codebase with improved maintainability
• Smart Defaults Engine — auto-adjusts documentation based on role complexity
• Severity-based output (CRITICAL / WARNING / INFO levels)
• Positive output framing — actionable suggestions instead of bare warnings
• Progressive help — brief --help by default, with --help-full for all options
• Preset system — four built-in presets covering personal, team, enterprise, and consulting use cases
• Suppression system — silence false-positive recommendations with audit trail and optional expiry
• Interactive setup wizard (docsible init) with optional CI/CD workflow generation

Installation

Create a virtual environment (recommended):

python3 -m venv docsible-env
source docsible-env/bin/activate

Install from PyPI:

pip install docsible

Quick Start

# Step 1 — run the interactive wizard (picks a preset, optionally generates CI/CD config)
docsible init

# Step 2 — generate documentation
docsible document role . --preset=team

# Step 3 — just analyze without writing files
docsible analyze role --role /path/to/role

# Step 4 — validate markdown without writing files
docsible validate role --role /path/to/role

Command Reference

docsible init

Runs a 3-step interactive wizard to configure Docsible for a project. Creates .docsible/config.yml and, optionally, a CI/CD workflow file.

# Interactive wizard
docsible init

# Non-interactive — apply a preset directly
docsible init --preset=team

# Target a specific directory
docsible init --path /path/to/project

# Overwrite an existing config
docsible init --force

Wizard steps:

1. Use case — choose personal / team / enterprise / consulting
2. Smart defaults — enable auto-adjustment based on role complexity
3. CI/CD integration — optionally generate a workflow file for GitHub Actions, GitLab CI, or Azure DevOps

docsible document role

Generate documentation for an Ansible role. Supports all flags from the legacy docsible role command, plus --preset.

# Document the role in the current directory
docsible document role .

# Specify an explicit path
docsible document role --role /path/to/role

# Apply a preset
docsible document role --role /path/to/role --preset=enterprise

# Include Mermaid diagrams and inline task comments
docsible document role --role ./my-role --graph --comments

# Preview without writing any files
docsible document role --role ./my-role --dry-run

# Document a collection
docsible document role --collection ./my-collection --graph

# Include a playbook in the output
docsible document role --role ./my-role --playbook ./site.yml --graph

Full flag reference:

Input Paths:
  -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

Output Control:
  -o, --output TEXT         Output README file name (default: README.md)
  -nob, --no-backup         Do not create a backup before overwriting
  -a, --append              Append to the existing README instead of replacing
  --dry-run                 Preview output without writing any files
  --validate/--no-validate  Validate markdown formatting before writing (default: on)
  --auto-fix                Automatically fix common markdown formatting issues
  --strict-validation       Fail if markdown validation errors are found

Content Sections:
  --no-vars                 Hide variable documentation
  --no-tasks                Hide task lists and task details
  --no-diagrams             Hide all Mermaid diagrams
  --no-examples             Hide example playbook sections
  --no-metadata             Hide role metadata, author, and license
  --no-handlers             Hide handlers section
  --include-complexity      Include complexity analysis section in README
  --minimal                 Generate minimal documentation (enables all --no-* flags)

Templates:
  --md-role-template        Path to the role markdown template file
  --md-collection-template  Path to the collection markdown template file
  --hybrid                  Use hybrid template (manual + auto-generated sections)

Visualization:
  -g, --graph               Generate Mermaid diagrams for role visualization
  -com, --comments          Extract and include inline task comments
  -tl, --task-line          Include source file line numbers for each task
  --simplify-diagrams       Show only high-level diagrams, hide detailed flowcharts

Analysis & Complexity:
  --complexity-report       Include role complexity analysis in documentation
  --simplification-report   Include detailed pattern analysis with simplification suggestions
  --show-dependencies       Generate task dependency matrix table
  --analyze-only            Analyze role complexity without generating documentation

Repository Integration:
  -ru, --repository-url TEXT  Repository base URL (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)

Preset:
  --preset [personal|team|enterprise|consultant]
                            Apply a built-in preset (see Presets section)

Output Framing:
  --positive / --neutral    Use positive/actionable output framing (default: positive)

docsible analyze role

Analyze a role's complexity and surface recommendations without generating or writing documentation.

docsible analyze role --role /path/to/role
docsible analyze role --role /path/to/role --preset=enterprise

docsible validate role

Validate the documentation for a role without writing any files. Runs in dry-run mode with strict markdown validation on by default.

docsible validate role --role /path/to/role
docsible validate role --role /path/to/role --no-strict

docsible suppress

Manage suppression rules that silence false-positive recommendations. Rules are stored in .docsible/suppress.yml.

# Add a suppression rule
docsible suppress add "no examples" --reason "Examples live in a separate repo"

# Add with an expiry date and file scope
docsible suppress add "no examples" --reason "Legacy role" --expires 90 --file "roles/webserver"

# Add using a regular expression pattern
docsible suppress add "missing (readme|examples)" --reason "Not applicable" --regex

# List all active suppression rules
docsible suppress list

# Remove a rule by its ID
docsible suppress remove <rule-id>

# Remove all expired rules
docsible suppress clean

docsible guide

Display interactive guides and tutorials in the terminal.

docsible guide getting-started
docsible guide troubleshooting
docsible guide smart-defaults

docsible role (legacy)

The original single-command interface still works and accepts all flags. A deprecation notice is printed to stderr.

docsible role --role /path/to/ansible/role --playbook /path/to/playbook.yml --graph
docsible role --collection ./my-collection --no-backup --graph

Use docsible document role for new workflows.

Presets

Presets bundle a curated set of flags suited to common use cases. Apply any preset with --preset on document, analyze, validate, or init.

Preset	Description
personal	Solo developers — fast, minimal output, no diagrams
team	Team collaboration — comprehensive docs, auto-fix, smart defaults
enterprise	Production/compliance — full validation, strict mode, all reports
consultant	Client deliverables — maximum detail, all diagrams and reports

docsible document role . --preset=personal
docsible document role . --preset=team
docsible document role . --preset=enterprise
docsible document role . --preset=consultant

Individual flags passed on the command line override preset defaults.

Suppression System

When Docsible surfaces recommendations that do not apply to a particular role (false positives), suppressions allow you to silence them persistently.

Suppressions are stored in .docsible/suppress.yml relative to the working directory. Each rule records a pattern, a mandatory reason, an optional file scope, an optional expiry date, and an optional approver for audit purposes.

# Silence a recommendation matching a substring
docsible suppress add "no examples" --reason "Examples live in a separate repo"

# Silence with a 90-day expiry and scope to one role
docsible suppress add "no examples" --reason "Legacy role" --expires 90 --file "roles/webserver"

# View current rules
docsible suppress list

# Clean out expired rules
docsible suppress clean

Hybrid Template

Use the --hybrid flag to generate a README with a mix of manual sections (for high-level narrative) and auto-generated sections (for accurate technical details):

docsible document role --role ./my-role --hybrid --graph --comments

The hybrid template includes:

• Manual sections: Quick Start, Architecture Overview, Example Playbooks, Testing, Compatibility
• Auto-generated sections: Task Execution Flow, Role Variables, Task Details, Dependencies, Role Metadata
• HTML comments (<!-- MANUALLY MAINTAINED --> / <!-- DOCSIBLE GENERATED -->) mark which sections to edit by hand

Data Sources

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

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

Example

Thermo core simulator

Prerequisites

Docsible requires Python 3.x and the following libraries:

• Click
• Jinja2
• PyYAML
• Pydantic

Comment Tags

On variables and defaults

The tool reads comments placed immediately before a variable, provided they begin with a recognized tag:

# title: — populates the Title column in README.md (short description of the variable)

# required: — populates the Required column in README.md

# choices: — populates the Choices column in README.md (optional)

On tasks

The tool reads all lines before each - name: entry that begin with #. Those comments are reported in the Comments column of the task 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.