ansible-doctor-enhanced 0.14.1
Enhanced Ansible role documentation generator with annotation support, logging, error handling, and reporting
License: Apache-2.0
Requires Python: <4.0,>=3.11
Keywords: ansible, documentation, parser, roles, annotations

# Ansible Doctor Enhanced

<!-- Version & License -->
[![Version](https://img.shields.io/badge/version-v0.14.0-blue)](https://github.com/K4M1coder/ansible-doctor-enhanced/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

<!-- Language Version & Code Quality Tools -->
[![Python](https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/imports-isort-1674b1?style=flat&logo=python)](https://pycqa.github.io/isort/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue)](http://mypy-lang.org/)

<!-- Coverage & Test Results -->
[![Coverage](https://img.shields.io/badge/coverage-79%25-red?logo=pytest)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)
[![Tests Passed](https://img.shields.io/badge/tests%20passed-2163%2F2213-brightgreen?logo=pytest)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)
[![Tests Skipped](https://img.shields.io/badge/tests%20skipped-50%2F2213-yellow?logo=pytest)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)
[![Tests Failed](https://img.shields.io/badge/tests%20failed-0%2F2213-brightgreen?logo=pytest)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)
[![Tests Warnings](https://img.shields.io/badge/tests%20warnings-99-yellow?logo=pytest)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)
[![Performance](https://img.shields.io/badge/perf%20%E2%9C%93-S%3A56ms%20%7C%20M%3A57ms%20%7C%20L%3A58ms-brightgreen)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions)

<!-- Build & CI Status -->
[![Pre-commit](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/pre-commit.yml/badge.svg?branch=dev)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/pre-commit.yml)
[![CI Windows](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/ci-windows.yml/badge.svg?branch=dev)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/ci-windows.yml)
[![Badges](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/badges.yml/badge.svg?branch=dev)](https://github.com/K4M1coder/ansible-doctor-enhanced/actions/workflows/badges.yml)

<!-- 
📊 Dynamic Badge Setup Available!
To enable auto-updating badges with live metrics (coverage %, mypy errors, test counts):
1. Follow setup guide: BADGE_SETUP_QUICKSTART.md
2. Replace static badges above with dynamic versions from docs/BADGES.md
3. Badges will auto-update after each CI run with real-time stats
-->

---

![Ansible Doctor](./docs/Ansible-Doctor-Enhanced.bmp)

> A modernized fork of ansible-doctor with enhanced logging, error handling, documentation generation, and reporting capabilities built on KISS, SMART, and SOLID principles.

## 🎯 Project Description

Ansible Doctor Enhanced is a comprehensive tool for automatically generating documentation from any Ansible project collection role plugins modules and inventory. It parses role structures, extracts metadata, variables, task tags, and inline annotations to produce high-quality, structured documentation in multiple formats. Built with specification-driven development using GitHub spec-kit methodology.

## 📑 Table of Contents

<!-- toc -->

- [🎯 Project Description](#-project-description)
- [✨ Key Features](#-key-features)
- [📦 Ansible Collection Support (New in v0.5.0)](#-ansible-collection-support-new-in-v050)
  - [Parse Collection Metadata](#parse-collection-metadata)
  - [Generate Collection Documentation](#generate-collection-documentation)
  - [Analyze Role Dependencies](#analyze-role-dependencies)
- [📊 Project Documentation Support (New in v0.6.0)](#-project-documentation-support-new-in-v060)
  - [Generate Project Documentation](#generate-project-documentation)
  - [Parse Project Structure](#parse-project-structure)
- [📑 Index Generation & Navigation (New in v0.5.0)](#-index-generation--navigation-new-in-v050)
  - [Generate Indexes](#generate-indexes)
  - [Filter Indexes](#filter-indexes)
  - [Embedded Section Indexes](#embedded-section-indexes)
- [🔗 Links & Cross-References (New in v0.12.0)](#-links--cross-references-new-in-v0120)
  - [Automatic Cross-References](#automatic-cross-references)
  - [Link Validation](#link-validation)
  - [External Resource Integration](#external-resource-integration)
  - [Index-Based Navigation](#index-based-navigation)
  - [Section Navigation](#section-navigation)
  - [Link Health Reporting](#link-health-reporting)
  - [Bidirectional Relationships](#bidirectional-relationships)
- [🌐 Internationalization (i18n) Support (New in v0.5.1)](#-internationalization-i18n-support-new-in-v051)
  - [Language Configuration](#language-configuration)
  - [Generate Multi-Language Documentation](#generate-multi-language-documentation)
  - [Custom Translations](#custom-translations)
  - [Template Translation Markers](#template-translation-markers)
- [🔍 Schema Validation & Documentation (New in v0.5.0)](#-schema-validation--documentation-new-in-v050)
  - [Configuration Validation](#configuration-validation)
  - [Schema Export](#schema-export)
  - [Format Conversion](#format-conversion)
  - [Data Model Validation](#data-model-validation)
  - [Schema Documentation](#schema-documentation)
- [🏗️ Architecture](#-architecture)
  - [Core Components](#core-components)
  - [Design Principles](#design-principles)
  - [Data Flow](#data-flow)
  - [Key Patterns](#key-patterns)
- [🚀 Installation](#-installation)
  - [Prerequisites](#prerequisites)
  - [From Source (Development)](#from-source-development)
- [⚙️ Configuration](#-configuration)
  - [Configuration File (`.ansibledoctor.yml`)](#configuration-file-ansibledoctoryml)
  - [Configuration Commands](#configuration-commands)
  - [Environment Variables](#environment-variables)
- [CI/CD Integration](#cicd-integration)
  - [Exit Codes](#exit-codes)
  - [Using in CI/CD Pipelines](#using-in-cicd-pipelines)
  - [Execution Reports](#execution-reports)
  - [Correlation IDs](#correlation-ids)
- [📚 Documentation](#-documentation)
- [🏗️ Project Architecture](#-project-architecture)
- [🛠️ Development](#-development)
  - [Setup Development Environment](#setup-development-environment)
  - [Running Tests](#running-tests)
  - [Running Tests](#running-tests-1)
- [🤝 Contributing](#-contributing)
- [📊 Project Status](#-project-status)
- [🔄 Version Compatibility](#-version-compatibility)
- [📊 Project Status](#-project-status-1)
  - [Test Metrics](#test-metrics)
  - [Completed Features](#completed-features)
    - [✅ Core Functionality (MVP)](#-core-functionality-mvp)
    - [🎯 Roadmap to v1.0.0](#-roadmap-to-v100)
- [📄 License](#-license)
- [🙏 Acknowledgments](#-acknowledgments)
- [📞 Support & Contact](#-support--contact)

<!-- tocstop -->

## ✨ Key Features

- **Test-Driven Development (TDD)**: Mandatory Red-Green-Refactor cycle with 80%+ code coverage
- **Domain-Driven Design (DDD)**: Ubiquitous Language from Ansible domain, Bounded Contexts, rich domain models
- **Intelligent Role Parsing**: Extract metadata from `meta/main.yml`, variables from `defaults/` and `vars/`, task tags, and inline documentation annotations
- **Annotation System**: Support for `@var`, `@tag`, `@todo`, `@example`, and `@meta` annotations with multiple formats (single-line, multiline, JSON)
- **Collection Support (v0.5.0)**: Parse, generate documentation, and analyze dependencies for Ansible Collections
- **Project Documentation (v0.6.0)**: Generate comprehensive project-level documentation with architecture diagrams, role/collection inventories, and multi-language support
- **Internationalization (v0.5.1)**: Initial i18n support with translation files for English, French and German and a Jinja2 `t()` filter for templates
- **Links & Cross-References (v0.12.0)**: Smart link management with automatic cross-references, broken link detection, external resource integration, and multiple navigation indexes
- **Code Quality & CI/CD (v0.14.0)**: Advanced quality gates with 16 dynamic badges, performance telemetry, and strict atomic commit validation
- **Structured Logging**: Advanced observability with structured logging, correlation IDs, and performance metrics
- **Error Handling**: Graceful error recovery with actionable suggestions and detailed context
- **Multiple Output Formats**: Generate documentation in Markdown, HTML, reStructuredText, and custom templates
- **CLI-First Design**: Scriptable command-line interface with JSON output for pipeline integration
- **Type-Safe**: Full type hints with mypy strict mode validation
- **Constitutional Governance**: 10 core principles ensuring quality, maintainability, and SOLID architecture

## 📦 Ansible Collection Support (New in v0.5.0)

Ansible Doctor Enhanced now provides comprehensive support for **Ansible Collections** with three powerful commands:

### Parse Collection Metadata

Extract and validate collection metadata from `galaxy.yml`:

```bash
# Parse collection metadata
poetry run ansible-doctor-enhanced collection parse ./my_namespace.my_collection

# Output to JSON file
poetry run ansible-doctor-enhanced collection parse ./my_namespace.my_collection --output metadata.json --pretty
```

### Generate Collection Documentation

Create professional README.md for your collection:

```bash
# Generate Markdown documentation (default)
# Output: docs/lang/en/collection_namespace.name/README.md
poetry run ansible-doctor-enhanced collection generate ./my_namespace.my_collection

# Generate HTML documentation
poetry run ansible-doctor-enhanced collection generate ./my_namespace.my_collection --format html

# Use legacy output structure (docs/README.md)
poetry run ansible-doctor-enhanced collection generate ./my_namespace.my_collection --legacy-output

# Use custom template
poetry run ansible-doctor-enhanced collection generate ./my_namespace.my_collection --template custom.md.j2
```

### Analyze Role Dependencies

Visualize and validate role dependencies within collections:

```bash
# Show dependency tree (ASCII)
poetry run ansible-doctor-enhanced collection analyze ./my_namespace.my_collection --show-dependencies

# Check for circular dependencies (CI/CD)
poetry run ansible-doctor-enhanced collection analyze ./my_namespace.my_collection --check-circular

# Export to Mermaid diagram
poetry run ansible-doctor-enhanced collection analyze ./my_namespace.my_collection --show-dependencies --output-format mermaid
```

**Example Output**:

```
Dependency Graph (TEXT format):
============================================================
└── database
    └── application
        └── webserver
```

**Features**:

- ✅ Parse `galaxy.yml` metadata (namespace, name, version, dependencies)
- ✅ Discover roles and plugins automatically
- ✅ Generate comprehensive collection README with installation instructions
- ✅ Detect circular role dependencies
- ✅ Export dependency graphs (ASCII tree, JSON, Mermaid)
- ✅ Multiple output formats (Markdown, HTML, RST)

**Documentation**: See [COLLECTION_GUIDE.md](docs/COLLECTION_GUIDE.md) for comprehensive usage guide with examples.

**Demo**: Try the included demo collection at `demo/demo_namespace.demo_collection/`

## 📊 Project Documentation Support (New in v0.6.0)

Ansible Doctor Enhanced now provides comprehensive **Project-level Documentation** generation with architecture visualization and multi-language support:

### Generate Project Documentation

Create professional project README with architecture diagrams and component inventories:

```bash
# Generate Markdown documentation (default)
poetry run ansible-doctor-enhanced project generate ./

# Generate HTML documentation
poetry run ansible-doctor-enhanced project generate ./ --format html

# Generate multi-language documentation
poetry run ansible-doctor-enhanced project generate ./ --languages en,fr,de

# Use legacy output path (for migration from older versions)
poetry run ansible-doctor-enhanced project generate ./ --legacy-output

# Use custom template
poetry run ansible-doctor-enhanced project generate ./ --template custom.md.j2

# Specify output directory
poetry run ansible-doctor-enhanced project generate ./ --output docs/
```

### Parse Project Structure

Extract and analyze project metadata, roles, collections, playbooks, and inventory:

```bash
# Parse project structure
poetry run ansible-doctor-enhanced project parse ./

# Output to JSON file
poetry run ansible-doctor-enhanced project parse ./ --output project.json --pretty
```

**Features**:

- ✅ Parse `ansible.cfg`, inventory files, playbooks, roles, and collections
- ✅ Generate project README with Mermaid architecture diagrams
- ✅ Multi-language documentation support with i18n
- ✅ Automatic slug-based output paths (`docs/ansibleproject_{projectname}/`)
- ✅ Multiple output formats (Markdown, HTML, RST)
- ✅ Custom template support

## 📑 Index Generation & Navigation (New in v0.5.0)

Ansible Doctor Enhanced provides comprehensive **Index Generation** with multiple visualization formats, filtering capabilities, and embedded section indexes:

### Generate Indexes

Create professional index pages for roles, plugins, and collections:

```bash
# List format (default) - Bulleted list with descriptions
ansible-doctor-enhanced collection generate ./my_collection --include-index

# Table format - Compact table view
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style table

# Tree format - Hierarchical structure with ASCII art
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style tree --index-depth 3

# Nested table - Collections with inline children display
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style nested-table --nested-depth 2

# Mermaid diagram - Visual flowchart with clickable nodes
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style diagram
```

### Filter Indexes

Filter components by tag, namespace, type, or custom metadata:

```bash
# Single filter - Show only web-tagged components
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style table \
    --filter 'tag:web'

# Multiple filters - AND logic (all must match)
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --index-style table \
    --filter 'tag:web' \
    --filter 'namespace:my_namespace'

# Filter by type
ansible-doctor-enhanced collection generate ./my_collection \
    --include-index --filter 'type:role'
```

### Embedded Section Indexes

Use `{{ index() }}` function in Jinja2 templates to embed indexes anywhere:

```jinja
## Available Roles

{{ index('roles', format='table') }}

## Web Infrastructure (Top 5)

{{ index('roles', format='list', filter='tag:web', limit=5) }}

## Plugins by Type

{{ index('plugins', format='table', group_by='metadata.plugin_type') }}
```

**Features**:

- ✅ **5 Index Formats**: list, table, tree, nested-table, diagram (Mermaid)
- ✅ **Hierarchical Organization**: Collections → Roles/Plugins/Playbooks
- ✅ **Embedded Sections**: `{{ index() }}` function for inline indexes
- ✅ **Advanced Filtering**: Filter by tag, namespace, type, metadata
- ✅ **Visual Diagrams**: Mermaid flowcharts and mindmaps with clickable nodes
- ✅ **Nested Tables**: Inline display of children with role/plugin counts
- ✅ **50+ Tests**: Comprehensive test coverage with TDD approach

**Example Output**:

**List Format:**

```markdown
# Roles Index

## [webserver](docs/roles/webserver.md)

Deploy and configure a web server with Nginx or Apache.

**Tags:** `web`, `nginx`, `apache`

**Dependencies:** common, firewall

---

## [database](docs/roles/database.md)

Deploy PostgreSQL or MySQL database servers.

**Tags:** `database`, `postgres`, `mysql`
```

**Tree Format:**

```
Collection: my_namespace.my_collection
├── Role: webserver (tags: web, nginx)
│   ├── Dependencies: common, firewall
│   └── Used by: app_server
├── Role: database (tags: database, postgres)
└── Plugin: web_config (type: module)
```

**Nested Table Format:**

```markdown
| Collection | Namespace | Roles | Plugins | Description |
|------------|-----------|-------|---------|-------------|
| [my_collection](docs/index.md) | my_namespace | 5 | 8 | Web infrastructure |
| ↳ **Roles:** | | webserver, database, cache | | |
| ↳ **Plugins:** | | web_config, db_backup | | |
```

**Mermaid Diagram:**

````markdown
```mermaid
graph TD
    collection[my_namespace.my_collection]
    webserver(webserver)
    database(database)
    
    collection --> webserver
    collection --> database
    webserver -.depends.-> common
    
    click webserver "docs/roles/webserver.md"
```
````

**Documentation**: See [INDEX_GUIDE.md](docs/INDEX_GUIDE.md) for comprehensive usage guide with examples.

**CLI Reference**:

- `--include-index`: Enable index generation
- `--index-style`: Format (list, table, tree, nested-table, diagram)
- `--index-format`: Page format (full, section)
- `--index-depth`: Maximum tree depth (default: 5)
- `--nested-depth`: Nesting depth for nested-table (default: 2)
- `--filter`: Filter by field:value (multiple allowed)

**Documentation**: See [PROJECT_COMPLETION.md](PROJECT_COMPLETION.md) for comprehensive usage guide.

**Demo**: Try the included demo project at `demo-role/` or `test-role/`

## 🔗 Links & Cross-References (New in v0.12.0)

Ansible Doctor Enhanced provides comprehensive **Link Management** with automatic cross-reference generation, broken link detection, and intelligent navigation features:

### Automatic Cross-References

Links are automatically generated between related documentation:

```bash
# Generate documentation with automatic cross-references
ansible-doctor-enhanced role ./my_role --output ./docs

# Links are generated for:
# - Dependencies (roles that this role depends on)
# - Parent collection (link back to collection)
# - Related roles (by tags or functionality)
# - Project context (breadcrumb navigation)
```

**Generated Links Include**:

```markdown
## Dependencies

- [common](../common/README.md)
- [database](../database/README.md)

**Part of Collection**: [namespace.collection](../../README.md)

## Related Roles

- [nginx](../nginx/README.md) - Web server configuration
- [haproxy](../haproxy/README.md) - Load balancer setup
```

### Link Validation

Validate all links in your documentation to catch broken links before deployment:

```bash
# Validate all links (internal + external)
ansible-doctor linkcheck ./docs

# Internal links only (fast)
ansible-doctor linkcheck ./docs --internal-only

# External links only (with caching)
ansible-doctor linkcheck ./docs --external-only

# JSON output for CI/CD
ansible-doctor linkcheck ./docs --format json --output validation.json

# Validate during generation
ansible-doctor role ./my_role --output ./docs --validate-links
```

**CI/CD Integration**:

```yaml
# .github/workflows/docs.yml
- name: Validate Documentation Links
  run: |
    ansible-doctor linkcheck ./docs --format json
    if [ $? -ne 0 ]; then
      echo "❌ Broken links detected!"
      exit 1
    fi
```

**Exit Codes**:

- `0`: All links valid ✅
- `1`: Broken links found ❌
- `2`: Validation error occurred ⚠️

### External Resource Integration

Automatically link to official Ansible documentation and Galaxy:

```bash
# Enable external link integration
ansible-doctor role ./my_role --output ./docs
```

**Automatic Links Generated For**:

- **Module Documentation**: `ansible.builtin.apt` → <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html>
- **Galaxy Pages**: Collections → <https://galaxy.ansible.com/namespace/collection>
- **Best Practices**: Keywords like "security", "vault", "molecule" link to official guides
- **Version-Specific**: Uses configured Ansible version (e.g., `/ansible/2.15/`)

**Configuration**:

```yaml
# .ansibledoctor.yml
ansible_version: "2.15"

external_links:
  enable_module_docs: true
  enable_galaxy_links: true
  enable_best_practices: true
  ansible_docs_base: "https://docs.ansible.com"
  galaxy_base: "https://galaxy.ansible.com"
```

### Index-Based Navigation

Multiple pathways to discover content:

```bash
# Generate documentation with indexes
ansible-doctor collection ./my_collection --output ./docs
```

**Generated Indexes**:

- **Alphabetical Index**: Group by first letter (A-Z, #)
- **Category Index**: Group by type (role, module, plugin)
- **Tag Index**: Group by tags with popularity sorting
- **Search Index**: Full-text search with relevance scoring

**Tag Navigation Example**:

```markdown
# Tags

## webserver (5 items)
- [apache](./apache/README.md) *role*
- [nginx](./nginx/README.md) *role*
- [haproxy](./haproxy/README.md) *role*

## database (3 items)
- [postgres](./postgres/README.md) *role*
- [mysql](./mysql/README.md) *role*

**Tags**: [`webserver`](../tags.md#tag-webserver), [`production`](../tags.md#tag-production)
```

### Section Navigation

Table of contents with anchor links for long documents:

```bash
# TOC automatically generated for documents with 5+ headings
ansible-doctor role ./my_role --output ./docs
```

**Generated TOC**:

```markdown
## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
  - [Requirements](#requirements)
  - [Dependencies](#dependencies)
- [Configuration](#configuration)
- [Usage](#usage)
```

**Features**:

- ✅ Automatic TOC generation for long documents
- ✅ Nested structure support (H2-H6)
- ✅ URL-safe anchor slugs
- ✅ Duplicate heading handling
- ✅ Mobile-responsive HTML TOC

### Link Health Reporting

Generate comprehensive link health reports:

```bash
# Markdown report
ansible-doctor linkreport ./docs --format markdown --output report.md

# HTML report with all links
ansible-doctor linkreport ./docs --format html --include-valid --output report.html

# JSON report grouped by file
ansible-doctor linkreport ./docs --format json --group-by file
```

**Report Includes**:

- Valid links count with ✅ indicator
- Warning links (redirects, slow responses)
- Broken links with file:line locations
- HTTP status codes for external links
- Suggested fixes for common issues

### Bidirectional Relationships

Track "links to" and "linked by" relationships:

```bash
# Generate documentation with relationship tracking
ansible-doctor collection ./my_collection --output ./docs
```

**Relationship Visualization**:

```mermaid
graph TD
    role_a -->|depends_on| role_b
    role_a -->|includes| role_c
    role_b <-->|references| role_d
```

**Features**:

- ✅ **Automatic Cross-References**: Links between related roles/collections/projects
- ✅ **Broken Link Detection**: Internal and external link validation
- ✅ **External Integration**: Official Ansible docs and Galaxy links
- ✅ **Multiple Indexes**: Alphabetical, category, tag, and search indexes
- ✅ **Section Navigation**: Auto-generated table of contents
- ✅ **Link Caching**: External link validation caching (< 30s for 1000+ docs)
- ✅ **Relationship Tracking**: Bidirectional "links to" / "linked by"
- ✅ **CI/CD Ready**: JSON output, exit codes, automated validation

**CLI Commands**:

- `ansible-doctor linkcheck`: Validate all links
- `ansible-doctor linkreport`: Generate link health report
- `ansible-doctor linkfix`: Interactive broken link fixing (coming soon)

**Documentation**: See [LINKS_GUIDE.md](docs/LINKS_GUIDE.md) for comprehensive usage guide with examples.

**Configuration**: See `.ansibledoctor.yml` for external link configuration options.

## 🌐 Internationalization (i18n) Support (New in v0.5.1)

Ansible Doctor Enhanced supports multi-language documentation generation through a translation system. Generate documentation in multiple languages from a single codebase with YAML-based translation files.

### Language Configuration

Configure language settings in `.ansibledoctor.yml`:

```yaml
# .ansibledoctor.yml
languages:
  default: en              # Default language
  enabled:                 # Languages to generate
    - en
    - fr
    - de
  fallback: en            # Fallback when translation missing
```

### Generate Multi-Language Documentation

```bash
# Generate project docs in multiple languages
poetry run ansible-doctor-enhanced project generate ./ --languages en,fr,de

# Generate in a single language
poetry run ansible-doctor-enhanced project generate ./ --language fr

# Output structure:
# docs/
# └── lang/
#     ├── en/README.md
#     ├── fr/README.md
#     └── de/README.md
```

### Custom Translations

Override default translations by creating custom translation files in your project:

```
.ansibledoctor/
└── translations/
    ├── en.yml    # English overrides
    ├── fr.yml    # French overrides
    └── de.yml    # German overrides
```

Translation file format:

```yaml
# translations/fr.yml
overview:
  title: "Aperçu"
  description: "Description du rôle"
variables:
  title: "Variables"
  required: "Variables Requises"
  optional: "Variables Optionnelles"
```

### Template Translation Markers

Use the `t()` filter in custom templates for translatable strings:

```jinja2
{# Using translation in templates #}
## {{ t('overview.title') }}

{{ t('overview.description') }}

{# With variable substitution #}
{{ t('install.version', version='1.0.0') }}

{# Pluralization support #}
{{ t('items.count', count=5) }}
```

**Supported Languages**: English (en), French (fr), German (de) - extensible with custom translation files.

## 🔍 Schema Validation & Documentation (New in v0.5.0)

Ansible Doctor Enhanced provides comprehensive **Schema Validation, Export, Conversion, and Documentation** capabilities for configuration files, data models, and documentation workflows.

### Configuration Validation

Validate `.ansibledoctor.yml` files against JSON Schema:

```bash
# Basic validation
ansible-doctor-enhanced schema validate .ansibledoctor.yml

# Strict mode (warnings as errors)
ansible-doctor-enhanced schema validate .ansibledoctor.yml --strict

# Verbose output with suggestions
ansible-doctor-enhanced schema validate .ansibledoctor.yml --verbose
```

**Example Output**:

```
✗ Configuration validation failed
  1 error(s):
    - output_format: Input should be 'markdown', 'html' or 'rst'
      Suggestion: Use one of the allowed values: markdown, html, rst
```

### Schema Export

Export JSON Schema definitions for IDE integration:

```bash
# Export to stdout
ansible-doctor-enhanced schema export config

# Export to file
ansible-doctor-enhanced schema export config --output config-schema.json

# OpenAPI format
ansible-doctor-enhanced schema export config --format openapi --output openapi.yaml
```

**IDE Integration** - Enable autocomplete and validation in VS Code:

```json
// .vscode/settings.json
{
  "yaml.schemas": {
    "./config-schema.json": ".ansibledoctor.yml"
  }
}
```

### Format Conversion

Convert configuration files between YAML, JSON, XML, and Mermaid:

```bash
# YAML to JSON (pretty)
ansible-doctor-enhanced schema convert .ansibledoctor.yml --to json --pretty

# YAML to XML
ansible-doctor-enhanced schema convert .ansibledoctor.yml --to xml --output config.xml

# Generate Mermaid diagram
ansible-doctor-enhanced schema convert .ansibledoctor.yml --to mermaid --output diagram.mmd
```

**Mermaid Output Example**:

```mermaid
graph TB
    root[Config]
    root --> output_format[output_format: markdown]
    root --> recursive[recursive: false]
    root --> template_dir[template_dir]
```

### Data Model Validation

Validate role and collection data against pydantic models:

```bash
# Validate role data
ansible-doctor-enhanced schema validate-model role role_data.yml

# Validate collection metadata
ansible-doctor-enhanced schema validate-model collection galaxy.yml

# Strict mode (warnings as errors)
ansible-doctor-enhanced schema validate-model role role.yml --strict-validation
```

**Example Validation**:

```
✓ Role data is valid
  1 warning(s):
    - metadata.description: Description is recommended but missing or empty
```

### Schema Documentation

Generate human-readable Markdown documentation from JSON Schema:

```bash
# Generate to stdout
ansible-doctor-enhanced schema docs config

# Save to file
ansible-doctor-enhanced schema docs config --output schema-docs.md
```

**Generated Documentation Example**:

```markdown
# ConfigModel

Configuration model for .ansibledoctor.yml files.

## Properties

### `output_format` *(required)*

**Type**: `string`

Documentation format (markdown, html, or rst).

**Allowed values**:
- `markdown`
- `html`
- `rst`

**Default**: `markdown`
```

**Features**:

- ✅ **Configuration Validation**: Validate `.ansibledoctor.yml` with strict mode
- ✅ **Schema Export**: JSON Schema Draft 2020-12 for IDE integration
- ✅ **Format Conversion**: YAML ↔ JSON ↔ XML ↔ Mermaid
- ✅ **Data Model Validation**: Validate roles and collections with pydantic
- ✅ **Schema Documentation**: Generate Markdown from JSON Schema
- ✅ **IDE Autocomplete**: VS Code, IntelliJ IDEA, PyCharm integration
- ✅ **Strict Mode**: Treat warnings as errors for CI/CD
- ✅ **Verbose Output**: Detailed error messages with suggestions

**Documentation**: See [SCHEMA_GUIDE.md](docs/SCHEMA_GUIDE.md) for comprehensive usage guide.

**CLI Commands**:

- `schema validate` - Validate configuration files
- `schema export` - Export JSON Schema definitions
- `schema convert` - Convert between formats
- `schema validate-model` - Validate data models
- `schema docs` - Generate schema documentation

## 🏗️ Architecture

Ansible Doctor Enhanced follows **Domain-Driven Design (DDD)** principles with clean architecture:

### Core Components

```
ansibledoctor/
├── models/           # Domain Models (DDD Value Objects & Entities)
│   ├── annotation.py    - Annotation value objects (@var, @tag, @todo, @example, @meta)
│   ├── metadata.py      - Role metadata entity (author, platforms, dependencies)
│   ├── variable.py      - Variable value object (name, type, value, annotations)
│   ├── tag.py           - Task tag value object
│   └── role.py          - Aggregate root combining all role information
├── parser/           # Domain Services (Anti-Corruption Layer)
│   ├── annotation_extractor.py  - Extract annotations from YAML comments
│   ├── metadata_parser.py       - Parse meta/main.yml into Metadata entity
│   ├── variable_parser.py       - Parse defaults/vars with type inference
│   ├── yaml_loader.py           - YAML loading abstraction (ruamel.yaml)
│   └── protocols.py             - Parser protocols (interfaces)
├── generator/        # Documentation Generation (NEW in v0.3.0)
│   ├── engine.py        - Jinja2 template engine with custom filters
│   ├── loaders.py       - Template loaders (filesystem, embedded)
│   ├── renderers.py     - Format-specific renderers (Markdown, HTML, RST)
│   ├── validator.py     - Template validation and variable checking
│   ├── filters.py       - Custom Jinja2 filters (rst_escape, code_block, etc.)
│   ├── models.py        - Generation models (TemplateContext, RenderResult)
│   ├── templates/       - Default templates for all output formats
│   └── protocols.py     - Generator protocols (TemplateLoader interface)
├── cli/              # Application Layer (CLI Interface)
│   └── __init__.py      - Click-based CLI with parse command
├── utils/            # Infrastructure Layer (Cross-cutting concerns)
│   ├── logging.py       - Structured logging with correlation IDs
│   └── paths.py         - Path validation and role structure checks
└── exceptions.py     # Domain Exceptions (AnsibleDoctorError hierarchy)
```

### Design Principles

1. **Immutability**: All domain models are frozen Pydantic models (value objects)
2. **Ubiquitous Language**: Terminology from Ansible domain (role, variable, meta, defaults, handlers)
3. **Bounded Contexts**: Clear separation between parsing (input) and generation (output - Phase 2)
4. **Type Safety**: 100% type hints with mypy --strict validation
5. **Testability**: Protocol-based design enabling dependency injection and mocking

### Data Flow

```
Role Directory → YAMLLoader → Parsers → Domain Models → CLI Output (JSON/Text)
                    ↓            ↓           ↓
                  YAML     Annotations  Immutable
                 Content    Extraction   Entities
```

### Key Patterns

- **Parser Protocol**: Abstract interface for all parsers (metadata, variable, tag)
- **Value Objects**: Annotation, Variable, Tag (immutable, equality by value)
- **Entity**: Metadata (identity by role name)
- **Aggregate Root**: Role (composition of metadata + variables + tags)
- **Anti-Corruption Layer**: Parsers shield domain from YAML library changes

## 🚀 Installation

### Prerequisites

- Python 3.11 or higher
- Poetry (for development)

### From Source (Development)

```bash
# Clone the repository
git clone https://github.com/yourusername/ansible-doctor-enhanced.git
cd ansible-doctor-enhanced

# Install with Poetry
poetry install

# Activate virtual environment
poetry shell
```

Alternatively, if you prefer to run directly from the source without relying on Poetry,
install the package into a local editable venv (makes the console script available):

```powershell
# Windows PowerShell (from repo root)
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .
# Now the command `ansible-doctor-enhanced` is available
ansible-doctor-enhanced --help
```

Or invoke the module directly:

```powershell
python -m ansibledoctor -- --help
```

```

### From PyPI (Coming Soon)

```bash
pip install ansible-doctor-enhanced
```

### Publish to PyPI (outline)

When you are ready to publish, we recommend creating a new release and uploading to the Python Package Index. A simple release flow (with Poetry) is:

```bash
# Build distribution files
poetry build

# Publish to PyPI (use Poetry's publish or twine)
# poetry publish --username <user> --password <pass>  # or configure Poetry auth
# or using twine:
python -m pip install build twine
python -m build
python -m twine upload dist/*
```

Notes:

- Make sure `tool.poetry.name` in `pyproject.toml` is set to the package name you want on PyPI (e.g., `ansible-doctor-enhanced`).
- Configure release version in `pyproject.toml` and update `CHANGELOG.md` before publishing.
- Use `test.pypi.org` to test the upload before publishing to production PyPI.

## 🏃 Quick Start

Parse an Ansible role and generate documentation:

```bash
# Parse a single role
ansible-doctor-enhanced parse --role-path ./my-ansible-role --output role-docs.json

# Parse with structured logging
ansible-doctor-enhanced parse --role-path ./my-ansible-role --log-level INFO

# Recursive parsing
ansible-doctor-enhanced parse --role-path ./roles/ --recursive

# Generate Markdown documentation
ansible-doctor-enhanced generate --input role-docs.json --output README.md --template readme
```

**Example Output:**

```json
{
  "name": "my-role",
  "metadata": {
    "author": "John Doe",
    "description": "Configures web server",
    "license": "MIT"
  },
  "variables": [
    {
      "name": "web_port",
      "value": 80,
      "type": "number",
      "description": "HTTP port for web server"
    }
  ],
  "tags": [
    {
      "name": "installation",
      "description": null,
      "usage_count": 3,
      "file_locations": ["tasks/main.yml:5", "tasks/install.yml:2"]
    },
    {
      "name": "configuration",
      "description": null,
      "usage_count": 2,
      "file_locations": ["tasks/main.yml:15", "tasks/configure.yml:1"]
    }
  ],
  "todos": [
    {
      "description": "Add SSL certificate validation",
      "file_path": "tasks/main.yml",
      "line_number": 42,
      "priority": "high"
    }
  ],
  "examples": [
    {
      "title": "Basic web server setup",
      "code": "web_port: 8080\nweb_ssl_enabled: true",
      "description": null,
      "language": "yaml"
    }
  ],
  "handlers": [
    {
      "name": "restart nginx",
      "tags": ["restart", "service"],
      "listen": ["nginx config changed"],
      "file_path": "handlers/main.yml",
      "line_number": 3
    },
    {
      "name": "reload nginx",
      "tags": ["reload"],
      "listen": ["nginx config updated"],
      "file_path": "handlers/main.yml",
      "line_number": 8
    }
  ],
  "existing_docs": {
    "readme_content": "# My Ansible Role\n\nConfigures web server...",
    "readme_format": "markdown",
    "changelog_content": "## [1.0.0] - 2025-01-01\n\n### Added\n- Initial release",
    "contributing_content": "# Contributing Guide\n\nPlease follow...",
    "license_content": "MIT License\n\nCopyright (c) 2025...",
    "license_type": "MIT",
    "templates_list": ["nginx.conf.j2", "vhost.conf.j2"],
    "files_list": ["index.html", "favicon.ico"]
  }
}
```

## 🎨 Theming & Customization (New in v0.8.0)

ansible-doctor-enhanced supports comprehensive theming for HTML documentation output.

### Template Variants

Choose from three built-in variants:

```bash
# Minimal - compact essential info
ansible-doctor role ./my-role --variant minimal --format html

# Detailed - full documentation (default)
ansible-doctor role ./my-role --variant detailed --format html

# Modern - contemporary card-based styling
ansible-doctor role ./my-role --variant modern --format html
```

### CSS Customization

Apply custom CSS via external URL or inline styles:

```bash
# External CSS theme
ansible-doctor role ./my-role --css-url https://cdn.example.com/theme.css

# Inline CSS overrides
ansible-doctor role ./my-role --css-inline ":root { --ad-color-primary: #dc2626; }"
```

### Dark Mode Toggle

Add a theme toggle button for dark/light mode:

```bash
ansible-doctor role ./my-role --format html --theme-toggle
```

Features:

- ✅ Respects `prefers-color-scheme` system preference
- ✅ Persists user choice to `localStorage`
- ✅ ARIA attributes for accessibility

### Color Schemes

```bash
# Force light/dark mode
ansible-doctor role ./my-role --color-scheme light
ansible-doctor role ./my-role --color-scheme dark

# Auto (respects OS preference - default)
ansible-doctor role ./my-role --color-scheme auto
```

### Configuration File

```yaml
# .ansibledoctor.yml
theme:
  variant: modern
  color_scheme: auto
  css_url: https://example.com/theme.css
  toggle_enabled: true
```

**Documentation:** See [TEMPLATE_GUIDE.md](docs/TEMPLATE_GUIDE.md) for CSS variables, custom templates, and advanced theming.

**Demo:** Try demo templates at `demo/templates/` and CSS examples at `demo/css/`.

## 📖 Usage

### Library API (Phase 2 Complete)

```python
from pathlib import Path
from ansibledoctor.parser import MetadataParser, RuamelYAMLLoader

# Initialize parser
yaml_loader = RuamelYAMLLoader()
metadata_parser = MetadataParser(yaml_loader)

# Parse role metadata
role_meta_dir = Path("/path/to/ansible-role/meta")
metadata = metadata_parser.parse_metadata(role_meta_dir)

# Access parsed metadata
print(f"Author: {metadata.author}")
print(f"License: {metadata.license}")
print(f"Platforms: {metadata.get_supported_platforms_summary()}")
print(f"Has dependencies: {metadata.has_dependencies()}")
```

### Generator API (Phase 9 Foundation Complete - NEW in v0.3.0)

```python
fro