1  # Documentation Testing Framework
  2  
  3  This directory contains the automated testing and validation framework for Planar documentation.
  4  
  5  ## Components
  6  
  7  ### Core Testing Modules
  8  
  9  - **`LinkValidator.jl`** - Module for validating internal and external links
 10  - **`ContentConsistency.jl`** - Module for checking content consistency and formatting
 11  - **`TestResultsReporter.jl`** - Module for generating test reports in various formats
 12  - **`config_validator.jl`** - Configuration validation and default settings
 13  
 14  ### Configuration
 15  
 16  - **`config.toml`** - Main configuration file for all testing options
 17  - **`runtests.jl`** - Main test runner script
 18  
 19  ### Test Execution
 20  
 21  The testing framework supports two main types of validation:
 22  
 23  1. **Link Validation** - Checks that all internal and external links are valid and accessible
 24  2. **Content Consistency** - Ensures consistent terminology, formatting, and style across documentation
 25  
 26  For code example review, see the [AI Code Block Review Guide](../maintenance/ai-code-block-review-guide.md) for systematic manual review procedures.
 27  
 28  ## Usage
 29  
 30  ### Running All Tests
 31  
 32  ```bash
 33  julia --project=Planar docs/test/runtests.jl
 34  ```
 35  
 36  ### Running Specific Test Types
 37  
 38  ```bash
 39  # Link validation only  
 40  julia --project=Planar docs/test/runtests.jl --skip-format
 41  
 42  # Content consistency only
 43  julia --project=Planar docs/test/runtests.jl --skip-links
 44  ```
 45  
 46  ### Configuration Options
 47  
 48  The testing framework can be configured via `config.toml`:
 49  
 50  - **Link Validation**: External link checking, timeout settings, skip patterns
 51  - **Content Consistency**: Terminology rules, format preferences, severity levels
 52  - **Reporting**: Output formats (HTML, JSON, summary), report locations
 53  
 54  ### CI Integration
 55  
 56  The framework integrates with GitHub Actions via `.github/workflows/docs-validation.yml`:
 57  
 58  - Runs on documentation changes
 59  - Tests against multiple Julia versions
 60  - Generates detailed reports
 61  - Provides CI-friendly output
 62  
 63  ## Features
 64  
 65  ### Link Validation
 66  
 67  - Validates internal relative links
 68  - Checks external HTTP/HTTPS links
 69  - Supports anchor link validation
 70  - Configurable timeout and retry settings
 71  - Batch processing for performance
 72  
 73  ### Content Consistency
 74  
 75  - Terminology consistency checking
 76  - Format validation (headings, code blocks, lists)
 77  - Cross-reference validation
 78  - Style guide compliance
 79  - Configurable rules and severity levels
 80  
 81  ### Reporting
 82  
 83  - HTML reports with detailed results
 84  - JSON reports for programmatic access
 85  - Summary reports for quick overview
 86  - CI-friendly output formats
 87  - Failure details and suggestions
 88  
 89  ## Implementation Status
 90  
 91  ✅ **Task 11.1: Add link validation and content consistency checking**
 92  - Link validation for internal and external links
 93  - Content consistency checking (terminology, format)
 94  - Enhanced configuration system
 95  - Comprehensive reporting framework
 96  - Updated CI workflows
 97  
 98  ## Requirements Addressed
 99  
100  This implementation addresses the following requirements from the docs-improvement spec:
101  
102  - **Requirement 10.1**: Format validation and consistency checking
103  - **Requirement 10.2**: Link validation and cross-reference checking
104  
105  For code example validation, the [AI Code Block Review Guide](../maintenance/ai-code-block-review-guide.md) provides comprehensive procedures for manual review and consistency checking.
106  
107  The framework ensures that documentation remains accurate, consistent, and up-to-date as the codebase evolves.