{"id":14984595,"url":"https://github.com/docsible/docsible","last_synced_at":"2025-04-05T03:12:06.644Z","repository":{"id":192922567,"uuid":"687740563","full_name":"docsible/docsible","owner":"docsible","description":"Auto documentation for Ansible roles and collections","archived":false,"fork":false,"pushed_at":"2025-03-19T20:28:49.000Z","size":117,"stargazers_count":81,"open_issues_count":4,"forks_count":15,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-31T09:08:16.601Z","etag":null,"topics":["ansible","ansible-collection","ansible-collections","ansible-galaxy","ansible-playbook","ansible-role","automation","awx","collections","documentation","generator","markdown","mermaid","mermaid-diagrams","python","role","roles","yml"],"latest_commit_sha":null,"homepage":"https://docsible.github.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docsible.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-05T23:06:30.000Z","updated_at":"2025-03-25T23:44:38.000Z","dependencies_parsed_at":"2023-09-06T00:25:32.828Z","dependency_job_id":"75a8e3da-c1bf-4a4e-92ac-b13f7c40714a","html_url":"https://github.com/docsible/docsible","commit_stats":null,"previous_names":["exaluc/docsible","docsible/docsible"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsible%2Fdocsible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsible%2Fdocsible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsible%2Fdocsible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsible%2Fdocsible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docsible","download_url":"https://codeload.github.com/docsible/docsible/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-collection","ansible-collections","ansible-galaxy","ansible-playbook","ansible-role","automation","awx","collections","documentation","generator","markdown","mermaid","mermaid-diagrams","python","role","roles","yml"],"created_at":"2024-09-24T14:09:18.853Z","updated_at":"2025-04-05T03:12:06.639Z","avatar_url":"https://github.com/docsible.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docsible\n\n## About\n\nDocsible 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.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Data Sources](#data-sources)\n- [Prerequisites](#prerequisites)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n- Generates a README in Markdown format\n- Scans and includes default variables and role-specific variables\n- Parses tasks, including special Ansible task types like 'block' and 'rescue'\n- Optionally includes playbook content in the README\n- CLI-based, easy to integrate into a CI/CD pipeline\n- Provides a templating feature to customize output\n- Supports multiple YAML files within `tasks`, `defaults`, `vars` directory\n- Includes meta-data like author and license from `meta/main.[yml/yaml]`\n- Generates a well-structured table for default and role-specific variables\n- Support for encrypted Ansible Vault variables\n\n## Installation\n\nHow to create virtual env with python3\n```bash\npython3 -m venv docsible\nsource docsible/bin/activate\n```\n\nTo install Docsible, you can run:\n\n```bash\npip install docsible\n```\n\n## Usage\n\nTo use Docsible, you can run the following command in your terminal:\n\n### Specific path\n```bash\ndocsible --role /path/to/ansible/role --playbook /path/to/playbook.yml --graph\n```\n\n### Document collection\n```bash\ndocsible --collection ./collections_tests/lucian/ --no-backup --graph\n```\n\n### Only role without playbook\n```bash\ndocsible --role /path/to/ansible/role # without include a playbook into readme\n```\n\n```bash\n$ docsible --help\nUsage: docsible [OPTIONS]\n\nOptions:\n  --role TEXT      Path to the Ansible role directory.\n  --collection TEXT Path to the Ansible collection directory.\n  --playbook TEXT  Path to the playbook file.\n  --graph          Generate Mermaid graph for tasks.\n  --no-backup      Do not backup the readme before remove.\n  --no-docsible    Do not create .docsible file and do not print relative variable to generated README.md.\n  --comments       Read comments from tasks files.\n  --md-template    Path to the markdown template file.\n  --append         Append to the existing README.md instead of replacing it.\n  --version        Show the module version.\n  --help           Show this message and exit.\n```\n\n### Flags\n\n- `--role`: Specifies the directory path to the Ansible role.\n- `--collection`: Specifies the directory path to the Ansible collection.\n- `--playbook`: Specifies the path to the Ansible playbook (Optional). ( Works only with roles )\n- `--graph`: Generate mermaid for role and playbook.\n- `--no-backup`: Ignore existent README.md and remove before generate a new one. (Optional).\n- `--comments`: Read comments from tasks files. (Optional).\n- `--md-template`: Specifies the path to the markdown template file (Optional). ( Works only with roles )\n- `--append`: Append existing readme.md if needed\n\n## Data Sources\n\nDocsible fetches information from the following files within the specified Ansible role:\n\n- `defaults/*.yml/yaml`: For default variables\n- `vars/*.yml/yaml`: For role-specific variables\n- `meta/main.yml/yaml`: For role metadata\n- `tasks/*.yml/yaml`: For tasks, including special task types and subfolders\n\n## Example\n[Thermo core simulator](https://github.com/docsible/thermo-core)\n\n## Prerequisites\n\nDocsible works with Python 3.x and requires the following libraries:\n\n- Click\n- Jinja2\n- PyYAML\n\n## TODO\n- Clean the code\n- Add more features\n- Multiple playbooks handle into mermaid for collection and role\n\n## About comments\n\nThis tool work whith several type of comments.\n\n### On variables and defaults\nThe tool read comments placed before a variable, only if it begin with specific tag:\n\n`# title:` This tag will be used for popiulate the column **Title** of the README.md. It is a short description of the variable\n\n`# required:` This tag will be used for popiulate the column **Required** of the README.md\n\n`# choices:` This optional tag will be used for popiulate the column **Choices** of the README.md\n\n### On tasks\n\nThe tool will read all the line before each `- name:` of the tasks that begin with `#`.\nAll comment will be reported to the column **Comments** of the tasks tables.\n\n## Contributing\n\nFor details on how to contribute, please read the [Contributing Guidelines](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocsible%2Fdocsible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocsible%2Fdocsible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocsible%2Fdocsible/lists"}