{"id":46574027,"url":"https://github.com/risadams/anodyse","last_synced_at":"2026-03-07T09:21:16.995Z","repository":{"id":341403628,"uuid":"1169995558","full_name":"risadams/anodyse","owner":"risadams","description":"Auto-generate user-facing documentation from Ansible playbooks and roles with @annotations. Parse YAML, extract structured comments, render Markdown \u0026 Mermaid diagrams, publish to docs portals.","archived":false,"fork":false,"pushed_at":"2026-03-01T16:58:57.000Z","size":251,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T17:55:40.921Z","etag":null,"topics":["ansible","automation","ci-cd","cli","devops","documentation","documentation-tool","infrastructure-as-code","mermaid","python","yaml-parser"],"latest_commit_sha":null,"homepage":"","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/risadams.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T14:49:33.000Z","updated_at":"2026-03-01T16:59:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/risadams/anodyse","commit_stats":null,"previous_names":["risadams/anodyse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/risadams/anodyse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risadams%2Fanodyse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risadams%2Fanodyse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risadams%2Fanodyse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risadams%2Fanodyse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/risadams","download_url":"https://codeload.github.com/risadams/anodyse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risadams%2Fanodyse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30210724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","automation","ci-cd","cli","devops","documentation","documentation-tool","infrastructure-as-code","mermaid","python","yaml-parser"],"created_at":"2026-03-07T09:21:15.306Z","updated_at":"2026-03-07T09:21:16.984Z","avatar_url":"https://github.com/risadams.png","language":"Python","readme":"# Anodyse\r\n\r\nAnodyse is a CLI that turns Ansible playbooks and roles into user-facing Markdown docs.\r\n\r\nIt scans files, extracts `@` annotations and TODO/FIXME comments, then renders:\r\n- one doc page per playbook/role\r\n- an `index.md` summary page\r\n\r\n## Why use it\r\n\r\n- Keeps operational docs close to automation code\r\n- Produces readable docs for consumers (not just Ansible authors)\r\n- Works for single files, role directories, or whole trees\r\n- Fits CI usage via clear exit codes\r\n\r\n## Install\r\n\r\nRequirements:\r\n- Python 3.11+\r\n\r\nInstall locally:\r\n\r\n```bash\r\npython -m pip install -e .\r\n```\r\n\r\nInstall with dev tools:\r\n\r\n```bash\r\npython -m pip install -e .[dev]\r\n```\r\n\r\nVerify:\r\n\r\n```bash\r\nanodyse --help\r\n```\r\n\r\n## Quick start\r\n\r\nGenerate docs from one playbook:\r\n\r\n```bash\r\nanodyse samples/web-server/deploy-nginx.yml --output docs/samples --verbose\r\n```\r\n\r\nGenerate docs from a directory (recursive discovery):\r\n\r\n```bash\r\nanodyse samples/ --output docs/samples --graph --verbose\r\n```\r\n\r\nTypical output:\r\n- `docs/samples/index.md`\r\n- one markdown file per discovered playbook/role\r\n\r\n## 🚀 Using Anodyse in CI/CD\r\n\r\nIntegrate Anodyse into your CI/CD pipeline to automatically generate documentation on every commit, pull request, or schedule.\r\n\r\n### Interactive Demo\r\n\r\n**This repository demonstrates the feature in action!** See:\r\n- 📖 **[Sample Generated Documentation](./samples/README-DOCS.md)** - How the workflows work\r\n- 📋 **[GitHub Actions Workflows](./.github/workflows/)** - Copy these to your own repo\r\n- 🔗 **Generated Samples**: Published to GitHub Pages (when available)\r\n\r\n### Integration Guides\r\n\r\nChoose your platform for detailed setup instructions:\r\n\r\n- **[CI Integration Guide](./docs/CI_INTEGRATION.md)** - Complete reference for all platforms\r\n- **[GitHub Actions](./docs/CI_INTEGRATION.md#github-actions-integration)** - 5-minute setup\r\n- **[GitLab CI/CD](./docs/CI_INTEGRATION.md#gitlab-cicd-integration)** - 5-minute setup\r\n- **[Generic CI Patterns](./docs/GENERIC_CI_INTEGRATION.md)** - Jenkins, Woodpecker, CircleCI, Travis, or custom\r\n- **[Publishing Guide](./docs/PUBLISHING.md)** - Publish to GitHub Pages, GitLab Pages, S3, and more\r\n- **[Platform Comparison](./docs/CI_PLATFORM_SUPPORT.md)** - Choose the right platform for your needs\r\n\r\n### Quick Start (GitHub Actions)\r\n\r\n1. Copy this workflow to `.github/workflows/anodyse-docs.yml`:\r\n\r\n```yaml\r\nname: Generate Docs\r\non:\r\n  push:\r\n    branches: [main]\r\n  pull_request:\r\n    branches: [main]\r\n\r\njobs:\r\n  generate:\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - uses: actions/checkout@v4\r\n      - uses: actions/setup-python@v5\r\n        with:\r\n          python-version: '3.11'\r\n      - run: pip install anodyse\r\n      - run: python -m anodyse . --output ./docs --verbose\r\n      - uses: actions/upload-artifact@v3\r\n        with:\r\n          path: ./docs\r\n      - uses: peaceiris/actions-gh-pages@v3\r\n        if: github.ref == 'refs/heads/main'\r\n        with:\r\n          github_token: ${{ secrets.GITHUB_TOKEN }}\r\n          publish_dir: ./docs\r\n```\r\n\r\n2. Commit and push to `main` - workflow runs automatically!\r\n3. See generated docs on GitHub Pages\r\n\r\n### All Supported Platforms\r\n\r\n| Platform | Setup | Difficulty | Notes |\r\n|----------|-------|-----------|-------|\r\n| **GitHub Actions** | 10 min | Beginner | Built-in to GitHub, free tier generous |\r\n| **GitLab CI/CD** | 10 min | Beginner | Built-in to GitLab, 400 min/month free |\r\n| **CircleCI** | 15 min | Intermediate | Cloud-based, 6,000 credits/month free |\r\n| **Jenkins** | 20 min | Intermediate | Self-hosted, on-premise support |\r\n| **Woodpecker** | 15 min | Intermediate | Modern Drone fork, lightweight |\r\n| **Travis CI** | 10 min | Beginner | ⚠️ Legacy platform, consider GitHub/GitLab |\r\n| **Generic Script** | 15 min | Intermediate | Use with any CI system or shell |\r\n\r\nSee [CI Platform Support Matrix](./docs/CI_PLATFORM_SUPPORT.md) for detailed comparison.\r\n\r\n## CLI\r\n\r\n```text\r\nanodyse TARGET [OPTIONS]\r\n```\r\n\r\n`TARGET` can be:\r\n- a playbook file (`.yml` / `.yaml`)\r\n- a role directory (contains `tasks/main.yml`)\r\n- a directory containing multiple playbooks/roles\r\n\r\nOptions:\r\n- `-o, --output PATH` output directory (default: `./docs`)\r\n- `--graph` include Mermaid flowchart diagrams\r\n- `--no-backup` do not create `.bak` files when overwriting\r\n- `--config PATH` explicit path to `.anodyse.yml`\r\n- `-v, --verbose` detailed processing output\r\n\r\nExit codes:\r\n- `0` success\r\n- `1` parse/runtime error\r\n- `2` generated with annotation warnings (for example missing `@title` or `@description`)\r\n\r\n## Supported annotations\r\n\r\nFile-level annotations:\r\n\r\n```yaml\r\n# @title Human-readable title\r\n# @description Plain-language summary\r\n# @param name: what this parameter means\r\n# @warning Caveat or prerequisite\r\n# @example Example invocation or usage\r\n# @tag category-or-label\r\n```\r\n\r\nTask-level annotations:\r\n\r\n```yaml\r\n# @task.description: Task summary\r\n# @task.note: Extra context\r\n# @task.warning: Task-specific warning\r\n# @task.tag: Task label\r\n```\r\n\r\nTODO tracking:\r\n- `TODO:` and `FIXME:` are collected from file headers and task comments\r\n- optional author form is supported (for example `TODO(ops): ...`)\r\n\r\n## Manifest config (`.anodyse.yml`)\r\n\r\nYou can control discovery with an optional manifest:\r\n\r\n```yaml\r\ninclude:\r\n  - samples/web-server/deploy-nginx.yml\r\n  - samples/database/deploy-postgresql.yml\r\n\r\nexclude:\r\n  - samples/missing-comments/deploy-unannotated.yml\r\n```\r\n\r\nRules:\r\n- If `include` is present, only those paths are used\r\n- Otherwise, `exclude` removes paths from discovered results\r\n- Missing declared paths produce warnings\r\n\r\nManifest lookup order:\r\n1. `--config` path (if provided)\r\n2. `.anodyse.yml` near the target\r\n3. `.anodyse.yml` in repo root (detected via `.git`)\r\n\r\n## Template overrides\r\n\r\nOverride built-in templates by adding files in:\r\n\r\n```text\r\n./.anodyse/templates/\r\n```\r\n\r\nSupported override filenames:\r\n- `playbook.md.j2`\r\n- `role.md.j2`\r\n- `index.md.j2`\r\n\r\nLookup order:\r\n1. local overrides in `./.anodyse/templates/`\r\n2. packaged defaults in `anodyse/templates/`\r\n\r\nExample (PowerShell):\r\n\r\n```powershell\r\nNew-Item -ItemType Directory -Path .anodyse/templates -Force | Out-Null\r\nCopy-Item samples/anodyse-template-overrides/templates/*.j2 .anodyse/templates/\r\nanodyse samples/web-server/deploy-nginx.yml --output docs/custom-templates --verbose\r\n```\r\n\r\n## Development\r\n\r\nRun tests:\r\n\r\n```bash\r\npytest\r\n```\r\n\r\nRun lint:\r\n\r\n```bash\r\nruff check .\r\n```\r\n\r\nBuild package:\r\n\r\n```bash\r\npython -m pip install build\r\npython -m build\r\n```\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisadams%2Fanodyse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frisadams%2Fanodyse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisadams%2Fanodyse/lists"}