# Documentation Quality Configuration for mypylogger v0.2.0
#
# This configuration file defines quality standards and validation rules
# for comprehensive documentation quality assurance.
#
# Requirements Addressed:
# - 16.1: Docstring coverage validation requiring 100% coverage
# - 16.2: Link validation to check all internal and external references
# - 16.3: Spelling and grammar checking for documentation content
# - 16.4: Documentation formatting and style consistency checks
# - 16.5: Documentation quality metrics and reporting

# Docstring Coverage Configuration
docstring_coverage:
  # Minimum required coverage percentage
  threshold: 100.0
  
  # Files and patterns to include in coverage analysis
  include_patterns:
    - "src/**/*.py"
  
  # Files and patterns to exclude from coverage analysis
  exclude_patterns:
    - "src/**/__pycache__/**"
    - "src/**/test_*.py"
    - "src/**/*_test.py"
  
  # Elements to ignore in coverage calculation
  ignore_options:
    - "init-method"      # Ignore __init__ methods
    - "init-module"      # Ignore __init__.py files
    - "magic"            # Ignore magic methods (__str__, __repr__, etc.)
    - "nested-functions" # Ignore nested functions
    - "private"          # Ignore private methods (starting with _)
    - "property-decorators" # Ignore @property decorated methods
    - "semiprivate"      # Ignore semiprivate methods (starting with single _)
  
  # Quality requirements for docstrings
  quality_requirements:
    min_length: 10  # Minimum docstring length in characters
    require_args: true     # Require Args section for functions with parameters
    require_returns: true  # Require Returns section for functions with return values
    require_raises: true   # Require Raises section for functions that raise exceptions
    google_style: true     # Enforce Google-style docstring format

# Link Validation Configuration
link_validation:
  # Timeout for external link checking (seconds)
  timeout: 30
  
  # Number of retries for failed links
  retries: 3
  
  # Patterns for links to ignore during validation
  ignore_patterns:
    - "localhost"
    - "127.0.0.1"
    - "example.com"
    - "example.org"
    - "test.example"
  
  # External domains that are allowed to fail (optional dependencies)
  allowed_failures:
    - "badges.shields.io"  # Badge services may be temporarily unavailable
  
  # Check external links (can be disabled for faster validation)
  check_external: true
  
  # Check anchors in external links
  check_anchors: true

# Spelling and Grammar Configuration
spelling_grammar:
  # Custom dictionary file for technical terms
  custom_dictionary: "docs/custom-dict.txt"
  
  # Built-in dictionaries to use
  dictionaries:
    - "en_US"
  
  # File patterns to check
  include_patterns:
    - "docs/**/*.rst"
    - "docs/**/*.md"
    - "README.md"
    - "CHANGELOG.md"
    - "src/**/*.py"  # Check docstrings in Python files
  
  # File patterns to exclude
  exclude_patterns:
    - "docs/build/**"
    - "**/__pycache__/**"
    - "**/.git/**"
    - "**/node_modules/**"
  
  # Technical terms that should be ignored
  technical_terms:
    - "mypylogger"
    - "JSON"
    - "stdlib"
    - "docstring"
    - "docstrings"
    - "autodoc"
    - "Sphinx"
    - "reStructuredText"
    - "PyPI"
    - "GitHub"
    - "API"
    - "APIs"
    - "CLI"
    - "UUID"
    - "timestamp"
    - "timestamps"
    - "formatter"
    - "formatters"
    - "handler"
    - "handlers"
    - "kwargs"
    - "args"
    - "bool"
    - "str"
    - "int"
    - "dict"
    - "tuple"
    - "async"
    - "await"
    - "asyncio"
    - "coroutine"
    - "pytest"
    - "mypy"
    - "ruff"
    - "uv"
    - "venv"
    - "virtualenv"
    - "pip"
    - "setuptools"
    - "wheel"
    - "TOML"
    - "YAML"
    - "XML"
    - "HTTP"
    - "HTTPS"
    - "URL"
    - "URLs"
    - "URI"
    - "URIs"
    - "regex"
    - "stdout"
    - "stderr"
    - "stdin"
    - "filesystem"
    - "namespace"
    - "namespaces"
    - "middleware"
    - "webhook"
    - "webhooks"
    - "microservice"
    - "microservices"
    - "containerized"
    - "Kubernetes"
    - "Docker"
    - "AWS"
    - "Lambda"
    - "CloudWatch"
    - "Splunk"
    - "Datadog"
    - "Dynatrace"

# Formatting and Style Configuration
formatting_style:
  # Maximum line length for documentation files
  max_line_length: 120
  
  # Preferred line length (soft limit)
  preferred_line_length: 80
  
  # Heading style requirements
  heading_styles:
    # Consistent underline characters for different heading levels
    level_1: "="  # Main titles
    level_2: "-"  # Section headers
    level_3: "^"  # Subsection headers
    level_4: "\""  # Sub-subsection headers
    level_5: "~"  # Paragraph headers
  
  # Indentation requirements
  indentation:
    spaces_per_level: 3  # Standard reStructuredText indentation
    use_spaces: true     # Use spaces instead of tabs
    consistent: true     # Require consistent indentation
  
  # Code block formatting
  code_blocks:
    require_language: true  # Require language specification for code blocks
    consistent_style: true  # Use consistent code block syntax
  
  # List formatting
  lists:
    consistent_bullets: true  # Use consistent bullet characters
    proper_indentation: true # Require proper list indentation
  
  # Table formatting
  tables:
    align_columns: true      # Require aligned table columns
    consistent_separators: true # Use consistent table separators
  
  # Whitespace rules
  whitespace:
    no_trailing: true        # No trailing whitespace
    no_multiple_blank: true  # No multiple consecutive blank lines
    end_with_newline: true   # Files should end with newline

# API Documentation Completeness Configuration
api_completeness:
  # Minimum requirements for API documentation
  requirements:
    # Function documentation requirements
    functions:
      require_docstring: true
      require_args_section: true
      require_returns_section: true
      require_raises_section: true
      require_examples: false  # Optional but recommended
    
    # Class documentation requirements
    classes:
      require_docstring: true
      require_attributes_section: false  # Optional
      require_methods_documented: true
      require_examples: false  # Optional but recommended
    
    # Module documentation requirements
    modules:
      require_docstring: true
      require_overview: true
      require_examples: false  # Optional but recommended
  
  # Elements to check for completeness
  check_elements:
    - "public_functions"
    - "public_classes"
    - "public_methods"
    - "module_level_docstrings"
  
  # Elements to exclude from completeness checking
  exclude_elements:
    - "private_methods"
    - "magic_methods"
    - "test_functions"
    - "setup_functions"

# Quality Metrics Configuration
quality_metrics:
  # Overall quality score calculation weights
  weights:
    docstring_coverage: 0.30    # 30% weight
    link_validation: 0.20       # 20% weight
    spelling_grammar: 0.20      # 20% weight
    formatting_style: 0.15      # 15% weight
    api_completeness: 0.15      # 15% weight
  
  # Minimum scores for each category (0-100)
  minimum_scores:
    docstring_coverage: 100     # Must be 100%
    link_validation: 95         # 95% of links must work
    spelling_grammar: 98        # 98% accuracy required
    formatting_style: 90        # 90% compliance required
    api_completeness: 100       # All APIs must be documented
  
  # Overall minimum quality score
  minimum_overall_score: 95
  
  # Badge generation thresholds
  badge_thresholds:
    excellent: 98   # Green badge
    good: 90        # Yellow badge
    needs_work: 80  # Orange badge
    # Below 80 = Red badge

# Reporting Configuration
reporting:
  # Output formats to generate
  formats:
    - "json"        # Machine-readable results
    - "html"        # Human-readable report
    - "markdown"    # Markdown summary
  
  # Report detail levels
  detail_levels:
    summary: true       # High-level summary
    detailed: true      # Detailed results per category
    verbose: false      # Include all raw output
  
  # Report sections to include
  sections:
    - "executive_summary"
    - "quality_metrics"
    - "detailed_results"
    - "recommendations"
    - "action_items"
  
  # Badge generation settings
  badges:
    generate: true
    output_dir: "badge-data"
    formats:
      - "shields.io"    # JSON format for shields.io
      - "svg"           # SVG badge files

# Validation Workflow Configuration
workflow:
  # Validation steps to run (in order)
  steps:
    - "docstring_coverage"
    - "api_completeness"
    - "link_validation"
    - "spelling_grammar"
    - "formatting_style"
  
  # Behavior on failures
  fail_fast: false        # Continue validation even if one step fails
  
  # Parallel execution settings
  parallel: false         # Run validations sequentially for better error reporting
  
  # Retry settings for network-dependent validations
  retry:
    max_attempts: 3
    delay_seconds: 5
    exponential_backoff: true
  
  # Timeout settings
  timeouts:
    per_validation: 300   # 5 minutes per validation step
    total: 1800          # 30 minutes total timeout