From 61fa430b3e8e4f4424908330e94bae94e255e751 Mon Sep 17 00:00:00 2001 From: rdmueller Date: Tue, 26 Nov 2024 17:14:21 +0000 Subject: [PATCH] deploy: 4d3ab720cc078a410ff81e241540f49578b27706 --- arc42/01_introduction_and_goals.html | 4 + arc42/02_architecture_constraints.html | 4 + arc42/03_system_scope_and_context.html | 4 + arc42/04_solution_strategy.html | 4 + arc42/05_building_block_view.html | 4 + arc42/06_runtime_view.html | 4 + arc42/07_deployment_view.html | 4 + arc42/08_concepts.html | 4 + arc42/09_architecture_decisions.html | 4 + arc42/10_quality_requirements.html | 4 + arc42/11_technical_risks.html | 4 + arc42/12_glossary.html | 4 + arc42/index.html | 4 + archive.html | 4 + feed.xml | 4 +- index.html | 4 + lunrjsindex.js | 74 +- manual/development.adoc.meta | 1 + manual/development.html | 727 +++++++++++ manual/index.adoc.meta | 1 + manual/index.html | 1586 ++++++++++++++++++++++++ manual/introduction.adoc.meta | 1 + manual/introduction.html | 654 ++++++++++ manual/rules.adoc.meta | 1 + manual/rules.html | 789 ++++++++++++ manual/testing.adoc.meta | 1 + manual/testing.html | 744 +++++++++++ manual/usage.adoc.meta | 1 + manual/usage.html | 805 ++++++++++++ search.html | 4 + sitemap.xml | 36 +- 31 files changed, 5471 insertions(+), 18 deletions(-) create mode 100755 manual/development.adoc.meta create mode 100644 manual/development.html create mode 100755 manual/index.adoc.meta create mode 100644 manual/index.html create mode 100755 manual/introduction.adoc.meta create mode 100644 manual/introduction.html create mode 100755 manual/rules.adoc.meta create mode 100644 manual/rules.html create mode 100755 manual/testing.adoc.meta create mode 100644 manual/testing.html create mode 100755 manual/usage.adoc.meta create mode 100644 manual/usage.html diff --git a/arc42/01_introduction_and_goals.html b/arc42/01_introduction_and_goals.html index 711bcb9..0d3f11a 100644 --- a/arc42/01_introduction_and_goals.html +++ b/arc42/01_introduction_and_goals.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/02_architecture_constraints.html b/arc42/02_architecture_constraints.html index bd8b642..2bc64ab 100644 --- a/arc42/02_architecture_constraints.html +++ b/arc42/02_architecture_constraints.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/03_system_scope_and_context.html b/arc42/03_system_scope_and_context.html index 13b7a36..0691bde 100644 --- a/arc42/03_system_scope_and_context.html +++ b/arc42/03_system_scope_and_context.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/04_solution_strategy.html b/arc42/04_solution_strategy.html index beb2a3c..d6c7bbe 100644 --- a/arc42/04_solution_strategy.html +++ b/arc42/04_solution_strategy.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/05_building_block_view.html b/arc42/05_building_block_view.html index a29aae6..75d762b 100644 --- a/arc42/05_building_block_view.html +++ b/arc42/05_building_block_view.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/06_runtime_view.html b/arc42/06_runtime_view.html index 63d78f2..f82afe3 100644 --- a/arc42/06_runtime_view.html +++ b/arc42/06_runtime_view.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/07_deployment_view.html b/arc42/07_deployment_view.html index 481fd1b..3475acd 100644 --- a/arc42/07_deployment_view.html +++ b/arc42/07_deployment_view.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/08_concepts.html b/arc42/08_concepts.html index 64bde22..56f7872 100644 --- a/arc42/08_concepts.html +++ b/arc42/08_concepts.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/09_architecture_decisions.html b/arc42/09_architecture_decisions.html index 3e606c4..0b3db78 100644 --- a/arc42/09_architecture_decisions.html +++ b/arc42/09_architecture_decisions.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/10_quality_requirements.html b/arc42/10_quality_requirements.html index 85d5596..edc74e5 100644 --- a/arc42/10_quality_requirements.html +++ b/arc42/10_quality_requirements.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/11_technical_risks.html b/arc42/11_technical_risks.html index 7fb951c..75fec18 100644 --- a/arc42/11_technical_risks.html +++ b/arc42/11_technical_risks.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/12_glossary.html b/arc42/12_glossary.html index 08620e3..6cf3966 100644 --- a/arc42/12_glossary.html +++ b/arc42/12_glossary.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/arc42/index.html b/arc42/index.html index d919476..f3f2133 100644 --- a/arc42/index.html +++ b/arc42/index.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/archive.html b/archive.html index 4c82f7f..10295f2 100644 --- a/archive.html +++ b/archive.html @@ -213,6 +213,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/feed.xml b/feed.xml index 39d63ce..e3f9e8e 100644 --- a/feed.xml +++ b/feed.xml @@ -6,8 +6,8 @@ JBake Bootstrap Template en-gb - Tue, 26 Nov 2024 17:00:57 +0000 - Tue, 26 Nov 2024 17:00:57 +0000 + Tue, 26 Nov 2024 17:14:20 +0000 + Tue, 26 Nov 2024 17:14:20 +0000 diff --git a/index.html b/index.html index e28d1d0..4024ca1 100644 --- a/index.html +++ b/index.html @@ -216,6 +216,10 @@ arc42 +
  • + manual +
    • +
    diff --git a/lunrjsindex.js b/lunrjsindex.js index 4123795..bd8a595 100644 --- a/lunrjsindex.js +++ b/lunrjsindex.js @@ -42,18 +42,18 @@ var documents = [ { "id": 5, - "uri": "arc42/10_quality_requirements.html", + "uri": "arc42/index.html", "menu": "arc42", - "title": "Quality Requirements", - "text": " Table of Contents Quality Requirements Quality Scenarios Quality Tree Quality Requirements Quality Scenarios Performance Scenarios Scenario Stimulus Response Priority Fast Document Processing Process 1000-line document Complete in < 1 second High Multiple File Processing Process 100 documents Complete in < 10 seconds Medium Memory Usage Process large document (10MB) Use < 100MB RAM High Startup Time Launch linter Ready in < 0.5 seconds Medium Reliability Scenarios Scenario Stimulus Response Priority Error Recovery Invalid input file Clear error message, continue with next file High Configuration Error Invalid rule configuration Detailed error message, use defaults High Plugin Failure Plugin crashes Isolate failure, continue with other rules Medium Resource Exhaustion System low on memory Graceful shutdown, save progress Medium Usability Scenarios Scenario Stimulus Response Priority Clear Error Messages Rule violation found Show file, line, and actionable message High Configuration Change rule settings Take effect without restart Medium Integration Use in CI pipeline Exit code reflects success/failure High Documentation Look up rule details Find explanation within 30 seconds Medium Quality Tree " + "title": "AsciiDoc Linter Architecture Documentation", + "text": " Table of Contents AsciiDoc Linter Architecture Documentation Introduction and Goals Requirements Overview Quality Goals Stakeholders Architecture Constraints Technical Constraints Organizational Constraints Conventions System Scope and Context Business Context Technical Context Solution Strategy Quality Goals and Architectural Approaches Technology Decisions Implementation Patterns Building Block View Level 1 - System Overview Level 2 - Core Components Level 3 - Rule Implementation Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Deployment View Infrastructure Level 1 Technical Infrastructure Security and Access Cross-cutting Concepts Domain Concepts Security Concepts Authentication and Authorization Input Validation Output Sanitization Development Concepts Test Strategy Release Process Configuration Concepts Rule Configuration Plugin System Architecture Decisions ADR 1: Rule Base Class Design Status Context Decision Consequences ADR 2: Finding Data Structure Status Context Decision Consequences ADR 3: Rule Implementation Strategy Status Context Decision Consequences ADR 4: Test Strategy Status Context Decision Consequences Quality Requirements Quality Scenarios Performance Scenarios Reliability Scenarios Usability Scenarios Quality Tree Technical Risks and Technical Debt Risk Analysis Technical Debt Current Technical Debt Planned Improvements Risk Matrix Glossary AsciiDoc Linter Architecture Documentation Introduction and Goals Requirements Overview The AsciiDoc Linter is a tool designed to ensure consistent formatting and structure in AsciiDoc documents. It helps teams maintain high-quality documentation by enforcing style rules and best practices. Key requirements include: Validate AsciiDoc heading structure Ensure consistent formatting Provide clear error messages Easy integration into existing workflows Extensible rule system Quality Goals Priority Quality Goal Motivation 1 Extensibility The system must be easily extensible with new rules to accommodate different documentation standards and requirements. 2 Reliability The linter must provide consistent and accurate results to maintain user trust. 3 Usability Error messages must be clear and actionable, helping users fix documentation issues efficiently. 4 Performance The linter should process documents quickly to maintain a smooth workflow. 5 Maintainability The code must be well-structured and documented to facilitate future enhancements. Stakeholders Role/Name Contact Expectations Documentation Writers various * Clear error messages * Consistent results * Quick feedback Documentation Maintainers various * Configurable rules * Reliable validation * Integration with existing tools Development Team dev team * Extensible architecture * Good test coverage * Clear documentation Technical Writers various * Support for AsciiDoc best practices * Customizable rule sets * Batch processing capabilities Architecture Constraints Technical Constraints Constraint Description Background Python 3.8+ The system must run on Python 3.8 or higher Need for modern language features and type hints Platform Independence Must run on Windows, Linux, and macOS Support for all major development platforms No External Dependencies Core functionality should work without external libraries Easy installation and deployment Memory Footprint Should process documents with minimal memory usage Support for large documentation projects Organizational Constraints Constraint Description Background Open Source Project must be open source under MIT license Community involvement and transparency Documentation All code must be documented with docstrings Maintainability and community contribution Test Coverage Minimum 90% test coverage required Quality assurance and reliability Version Control Git-based development with feature branches Collaborative development process Conventions Convention Description Background Code Style Follow PEP 8 guidelines Python community standards Type Hints Use type hints throughout the code Code clarity and IDE support Commit Messages Follow conventional commits specification Clear change history Documentation Format Use AsciiDoc for all documentation Dogfooding our own tool System Scope and Context Business Context Technical Context Solution Strategy Quality Goals and Architectural Approaches Quality Goal Solution Approach Details Extensibility * Abstract base classes * Plugin architecture * Clear interfaces * New rules can be added by extending base classes * Plugin system allows external rule packages * Well-defined interfaces for rule implementation Reliability * Comprehensive testing * Strong typing * Defensive programming * High test coverage * Type hints throughout the code * Careful input validation Usability * Clear error messages * Context information * Configuration options * Detailed error descriptions * Line and column information * Configurable rule severity Performance * Efficient algorithms * Lazy loading * Caching * Line-by-line processing * Rules loaded on demand * Cache parsing results Maintainability * Clean architecture * SOLID principles * Documentation * Clear separation of concerns * Single responsibility principle * Comprehensive documentation Technology Decisions Technology Decision Rationale Python Primary implementation language * Strong standard library * Great text processing capabilities * Wide adoption in tooling Regular Expressions Pattern matching * Built into Python * Efficient for text processing * Well understood by developers YAML Configuration format * Human readable * Standard format * Good library support unittest Testing framework * Part of Python standard library * Well known to developers * Good IDE support Implementation Patterns Building Block View Level 1 - System Overview Level 2 - Core Components Level 3 - Rule Implementation Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Deployment View Infrastructure Level 1 Technical Infrastructure Security and Access Cross-cutting Concepts Domain Concepts Security Concepts Authentication and Authorization Package distribution secured via PyPI authentication Configuration files with restricted access Signed releases with GPG keys Input Validation Strict content validation Safe file handling Memory usage limits Output Sanitization Escaped error messages Safe file paths handling Controlled error reporting Development Concepts Test Strategy Release Process Configuration Concepts Rule Configuration rules: heading_hierarchy: enabled: true severity: error options: max_level: 6 heading_format: enabled: true severity: warning options: require_space: true require_capitalization: true Plugin System Architecture Decisions ADR 1: Rule Base Class Design Status Accepted Context We need a flexible and extensible way to implement different linting rules for AsciiDoc documents. Decision We will use an abstract base class Rule with a defined interface that all concrete rules must implement. Consequences Positive Consistent interface for all rules Easy to add new rules Clear separation of concerns Simplified testing through common interface Negative Additional abstraction layer Slight performance overhead ADR 2: Finding Data Structure Status Accepted Context Rule violations need to be reported in a consistent and informative way. Decision We will use a Finding data class with fields for message, severity, position, rule ID, and context. Consequences Positive Structured error reporting Rich context for violations Consistent error format Negative More complex than simple string messages Requires more memory for storing findings ADR 3: Rule Implementation Strategy Status Accepted Context Rules need to process AsciiDoc content and identify violations efficiently. Decision Each rule will process the content line by line, using regular expressions for pattern matching. Consequences Positive Simple implementation Good performance for most cases Easy to understand and maintain Negative Limited context awareness May miss some complex patterns Regular expressions can become complex ADR 4: Test Strategy Status Accepted Context Rules need to be thoroughly tested to ensure reliable operation. Decision Each rule will have its own test class with multiple test methods covering various scenarios. Consequences Positive High test coverage Clear test organization Easy to add new test cases Negative More maintenance effort Longer test execution time :jbake-status: published :jbake-order: 10 :jbake-type: page_toc :jbake-menu: arc42 :jbake-title: Quality Requirements Quality Requirements Quality Scenarios Performance Scenarios Scenario Stimulus Response Priority Fast Document Processing Process 1000-line document Complete in < 1 second High Multiple File Processing Process 100 documents Complete in < 10 seconds Medium Memory Usage Process large document (10MB) Use < 100MB RAM High Startup Time Launch linter Ready in < 0.5 seconds Medium Reliability Scenarios Scenario Stimulus Response Priority Error Recovery Invalid input file Clear error message, continue with next file High Configuration Error Invalid rule configuration Detailed error message, use defaults High Plugin Failure Plugin crashes Isolate failure, continue with other rules Medium Resource Exhaustion System low on memory Graceful shutdown, save progress Medium Usability Scenarios Scenario Stimulus Response Priority Clear Error Messages Rule violation found Show file, line, and actionable message High Configuration Change rule settings Take effect without restart Medium Integration Use in CI pipeline Exit code reflects success/failure High Documentation Look up rule details Find explanation within 30 seconds Medium Quality Tree Technical Risks and Technical Debt Risk Analysis Risk Description Impact Probability Mitigation Performance Degradation Rule processing becomes slow with many rules High Medium * Profile rule execution * Implement rule caching * Optimize core algorithms Memory Leaks Long-running processes accumulate memory High Low * Regular memory profiling * Automated testing * Resource cleanup False Positives Rules report incorrect violations Medium High * Extensive test cases * User feedback system * Rule configuration options Plugin Conflicts Custom rules interfere with core rules Medium Medium * Plugin isolation * Version compatibility checks * Clear plugin API Technical Debt Current Technical Debt Area Description Impact Priority Test Coverage Some edge cases not covered Medium High Documentation Some advanced features poorly documented Medium Medium Error Handling Some error cases not specifically handled High High Configuration Hard-coded values that should be configurable Low Low Planned Improvements Risk Matrix Glossary Term Definition Additional Information AsciiDoc Lightweight markup language for documentation Similar to Markdown, but with more features for technical documentation Linter Tool that analyzes source code or text for potential errors Focuses on style, format, and structure issues Rule Individual check that validates specific aspects Can be enabled/disabled and configured Finding Result of a rule check indicating a potential issue Contains message, severity, and location information Severity Importance level of a finding ERROR, WARNING, or INFO Position Location in a document where an issue was found Contains line and optional column information Plugin Extension that adds additional functionality Can provide custom rules and configurations CI/CD Continuous Integration/Continuous Deployment Automated build, test, and deployment process PyPI Python Package Index Central repository for Python packages Virtual Environment Isolated Python runtime environment Manages project-specific dependencies Type Hints Python type annotations Helps with code understanding and static analysis Unit Test Test of individual components Ensures correct behavior of specific functions Integration Test Test of component interactions Verifies system behavior as a whole Coverage Measure of code tested by automated tests Usually expressed as percentage Technical Debt Development shortcuts that need future attention Balance between quick delivery and maintainability " }, { "id": 6, - "uri": "arc42/index.html", + "uri": "arc42/10_quality_requirements.html", "menu": "arc42", - "title": "AsciiDoc Linter Architecture Documentation", - "text": " Table of Contents AsciiDoc Linter Architecture Documentation Introduction and Goals Requirements Overview Quality Goals Stakeholders Architecture Constraints Technical Constraints Organizational Constraints Conventions System Scope and Context Business Context Technical Context Solution Strategy Quality Goals and Architectural Approaches Technology Decisions Implementation Patterns Building Block View Level 1 - System Overview Level 2 - Core Components Level 3 - Rule Implementation Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Deployment View Infrastructure Level 1 Technical Infrastructure Security and Access Cross-cutting Concepts Domain Concepts Security Concepts Authentication and Authorization Input Validation Output Sanitization Development Concepts Test Strategy Release Process Configuration Concepts Rule Configuration Plugin System Architecture Decisions ADR 1: Rule Base Class Design Status Context Decision Consequences ADR 2: Finding Data Structure Status Context Decision Consequences ADR 3: Rule Implementation Strategy Status Context Decision Consequences ADR 4: Test Strategy Status Context Decision Consequences Quality Requirements Quality Scenarios Performance Scenarios Reliability Scenarios Usability Scenarios Quality Tree Technical Risks and Technical Debt Risk Analysis Technical Debt Current Technical Debt Planned Improvements Risk Matrix Glossary AsciiDoc Linter Architecture Documentation Introduction and Goals Requirements Overview The AsciiDoc Linter is a tool designed to ensure consistent formatting and structure in AsciiDoc documents. It helps teams maintain high-quality documentation by enforcing style rules and best practices. Key requirements include: Validate AsciiDoc heading structure Ensure consistent formatting Provide clear error messages Easy integration into existing workflows Extensible rule system Quality Goals Priority Quality Goal Motivation 1 Extensibility The system must be easily extensible with new rules to accommodate different documentation standards and requirements. 2 Reliability The linter must provide consistent and accurate results to maintain user trust. 3 Usability Error messages must be clear and actionable, helping users fix documentation issues efficiently. 4 Performance The linter should process documents quickly to maintain a smooth workflow. 5 Maintainability The code must be well-structured and documented to facilitate future enhancements. Stakeholders Role/Name Contact Expectations Documentation Writers various * Clear error messages * Consistent results * Quick feedback Documentation Maintainers various * Configurable rules * Reliable validation * Integration with existing tools Development Team dev team * Extensible architecture * Good test coverage * Clear documentation Technical Writers various * Support for AsciiDoc best practices * Customizable rule sets * Batch processing capabilities Architecture Constraints Technical Constraints Constraint Description Background Python 3.8+ The system must run on Python 3.8 or higher Need for modern language features and type hints Platform Independence Must run on Windows, Linux, and macOS Support for all major development platforms No External Dependencies Core functionality should work without external libraries Easy installation and deployment Memory Footprint Should process documents with minimal memory usage Support for large documentation projects Organizational Constraints Constraint Description Background Open Source Project must be open source under MIT license Community involvement and transparency Documentation All code must be documented with docstrings Maintainability and community contribution Test Coverage Minimum 90% test coverage required Quality assurance and reliability Version Control Git-based development with feature branches Collaborative development process Conventions Convention Description Background Code Style Follow PEP 8 guidelines Python community standards Type Hints Use type hints throughout the code Code clarity and IDE support Commit Messages Follow conventional commits specification Clear change history Documentation Format Use AsciiDoc for all documentation Dogfooding our own tool System Scope and Context Business Context Technical Context Solution Strategy Quality Goals and Architectural Approaches Quality Goal Solution Approach Details Extensibility * Abstract base classes * Plugin architecture * Clear interfaces * New rules can be added by extending base classes * Plugin system allows external rule packages * Well-defined interfaces for rule implementation Reliability * Comprehensive testing * Strong typing * Defensive programming * High test coverage * Type hints throughout the code * Careful input validation Usability * Clear error messages * Context information * Configuration options * Detailed error descriptions * Line and column information * Configurable rule severity Performance * Efficient algorithms * Lazy loading * Caching * Line-by-line processing * Rules loaded on demand * Cache parsing results Maintainability * Clean architecture * SOLID principles * Documentation * Clear separation of concerns * Single responsibility principle * Comprehensive documentation Technology Decisions Technology Decision Rationale Python Primary implementation language * Strong standard library * Great text processing capabilities * Wide adoption in tooling Regular Expressions Pattern matching * Built into Python * Efficient for text processing * Well understood by developers YAML Configuration format * Human readable * Standard format * Good library support unittest Testing framework * Part of Python standard library * Well known to developers * Good IDE support Implementation Patterns Building Block View Level 1 - System Overview Level 2 - Core Components Level 3 - Rule Implementation Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Deployment View Infrastructure Level 1 Technical Infrastructure Security and Access Cross-cutting Concepts Domain Concepts Security Concepts Authentication and Authorization Package distribution secured via PyPI authentication Configuration files with restricted access Signed releases with GPG keys Input Validation Strict content validation Safe file handling Memory usage limits Output Sanitization Escaped error messages Safe file paths handling Controlled error reporting Development Concepts Test Strategy Release Process Configuration Concepts Rule Configuration rules: heading_hierarchy: enabled: true severity: error options: max_level: 6 heading_format: enabled: true severity: warning options: require_space: true require_capitalization: true Plugin System Architecture Decisions ADR 1: Rule Base Class Design Status Accepted Context We need a flexible and extensible way to implement different linting rules for AsciiDoc documents. Decision We will use an abstract base class Rule with a defined interface that all concrete rules must implement. Consequences Positive Consistent interface for all rules Easy to add new rules Clear separation of concerns Simplified testing through common interface Negative Additional abstraction layer Slight performance overhead ADR 2: Finding Data Structure Status Accepted Context Rule violations need to be reported in a consistent and informative way. Decision We will use a Finding data class with fields for message, severity, position, rule ID, and context. Consequences Positive Structured error reporting Rich context for violations Consistent error format Negative More complex than simple string messages Requires more memory for storing findings ADR 3: Rule Implementation Strategy Status Accepted Context Rules need to process AsciiDoc content and identify violations efficiently. Decision Each rule will process the content line by line, using regular expressions for pattern matching. Consequences Positive Simple implementation Good performance for most cases Easy to understand and maintain Negative Limited context awareness May miss some complex patterns Regular expressions can become complex ADR 4: Test Strategy Status Accepted Context Rules need to be thoroughly tested to ensure reliable operation. Decision Each rule will have its own test class with multiple test methods covering various scenarios. Consequences Positive High test coverage Clear test organization Easy to add new test cases Negative More maintenance effort Longer test execution time :jbake-status: published :jbake-order: 10 :jbake-type: page_toc :jbake-menu: arc42 :jbake-title: Quality Requirements Quality Requirements Quality Scenarios Performance Scenarios Scenario Stimulus Response Priority Fast Document Processing Process 1000-line document Complete in < 1 second High Multiple File Processing Process 100 documents Complete in < 10 seconds Medium Memory Usage Process large document (10MB) Use < 100MB RAM High Startup Time Launch linter Ready in < 0.5 seconds Medium Reliability Scenarios Scenario Stimulus Response Priority Error Recovery Invalid input file Clear error message, continue with next file High Configuration Error Invalid rule configuration Detailed error message, use defaults High Plugin Failure Plugin crashes Isolate failure, continue with other rules Medium Resource Exhaustion System low on memory Graceful shutdown, save progress Medium Usability Scenarios Scenario Stimulus Response Priority Clear Error Messages Rule violation found Show file, line, and actionable message High Configuration Change rule settings Take effect without restart Medium Integration Use in CI pipeline Exit code reflects success/failure High Documentation Look up rule details Find explanation within 30 seconds Medium Quality Tree Technical Risks and Technical Debt Risk Analysis Risk Description Impact Probability Mitigation Performance Degradation Rule processing becomes slow with many rules High Medium * Profile rule execution * Implement rule caching * Optimize core algorithms Memory Leaks Long-running processes accumulate memory High Low * Regular memory profiling * Automated testing * Resource cleanup False Positives Rules report incorrect violations Medium High * Extensive test cases * User feedback system * Rule configuration options Plugin Conflicts Custom rules interfere with core rules Medium Medium * Plugin isolation * Version compatibility checks * Clear plugin API Technical Debt Current Technical Debt Area Description Impact Priority Test Coverage Some edge cases not covered Medium High Documentation Some advanced features poorly documented Medium Medium Error Handling Some error cases not specifically handled High High Configuration Hard-coded values that should be configurable Low Low Planned Improvements Risk Matrix Glossary Term Definition Additional Information AsciiDoc Lightweight markup language for documentation Similar to Markdown, but with more features for technical documentation Linter Tool that analyzes source code or text for potential errors Focuses on style, format, and structure issues Rule Individual check that validates specific aspects Can be enabled/disabled and configured Finding Result of a rule check indicating a potential issue Contains message, severity, and location information Severity Importance level of a finding ERROR, WARNING, or INFO Position Location in a document where an issue was found Contains line and optional column information Plugin Extension that adds additional functionality Can provide custom rules and configurations CI/CD Continuous Integration/Continuous Deployment Automated build, test, and deployment process PyPI Python Package Index Central repository for Python packages Virtual Environment Isolated Python runtime environment Manages project-specific dependencies Type Hints Python type annotations Helps with code understanding and static analysis Unit Test Test of individual components Ensures correct behavior of specific functions Integration Test Test of component interactions Verifies system behavior as a whole Coverage Measure of code tested by automated tests Usually expressed as percentage Technical Debt Development shortcuts that need future attention Balance between quick delivery and maintainability " + "title": "Quality Requirements", + "text": " Table of Contents Quality Requirements Quality Scenarios Quality Tree Quality Requirements Quality Scenarios Performance Scenarios Scenario Stimulus Response Priority Fast Document Processing Process 1000-line document Complete in < 1 second High Multiple File Processing Process 100 documents Complete in < 10 seconds Medium Memory Usage Process large document (10MB) Use < 100MB RAM High Startup Time Launch linter Ready in < 0.5 seconds Medium Reliability Scenarios Scenario Stimulus Response Priority Error Recovery Invalid input file Clear error message, continue with next file High Configuration Error Invalid rule configuration Detailed error message, use defaults High Plugin Failure Plugin crashes Isolate failure, continue with other rules Medium Resource Exhaustion System low on memory Graceful shutdown, save progress Medium Usability Scenarios Scenario Stimulus Response Priority Clear Error Messages Rule violation found Show file, line, and actionable message High Configuration Change rule settings Take effect without restart Medium Integration Use in CI pipeline Exit code reflects success/failure High Documentation Look up rule details Find explanation within 30 seconds Medium Quality Tree " }, { @@ -90,22 +90,70 @@ var documents = [ { "id": 11, - "uri": "arc42/06_runtime_view.html", + "uri": "arc42/02_architecture_constraints.html", "menu": "arc42", - "title": "Runtime View", - "text": " Table of Contents Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence " + "title": "Architecture Constraints", + "text": " Table of Contents Architecture Constraints Technical Constraints Organizational Constraints Conventions Architecture Constraints Technical Constraints Constraint Description Background Python 3.8+ The system must run on Python 3.8 or higher Need for modern language features and type hints Platform Independence Must run on Windows, Linux, and macOS Support for all major development platforms No External Dependencies Core functionality should work without external libraries Easy installation and deployment Memory Footprint Should process documents with minimal memory usage Support for large documentation projects Organizational Constraints Constraint Description Background Open Source Project must be open source under MIT license Community involvement and transparency Documentation All code must be documented with docstrings Maintainability and community contribution Test Coverage Minimum 90% test coverage required Quality assurance and reliability Version Control Git-based development with feature branches Collaborative development process Conventions Convention Description Background Code Style Follow PEP 8 guidelines Python community standards Type Hints Use type hints throughout the code Code clarity and IDE support Commit Messages Follow conventional commits specification Clear change history Documentation Format Use AsciiDoc for all documentation Dogfooding our own tool " }, { "id": 12, - "uri": "arc42/02_architecture_constraints.html", + "uri": "arc42/06_runtime_view.html", "menu": "arc42", - "title": "Architecture Constraints", - "text": " Table of Contents Architecture Constraints Technical Constraints Organizational Constraints Conventions Architecture Constraints Technical Constraints Constraint Description Background Python 3.8+ The system must run on Python 3.8 or higher Need for modern language features and type hints Platform Independence Must run on Windows, Linux, and macOS Support for all major development platforms No External Dependencies Core functionality should work without external libraries Easy installation and deployment Memory Footprint Should process documents with minimal memory usage Support for large documentation projects Organizational Constraints Constraint Description Background Open Source Project must be open source under MIT license Community involvement and transparency Documentation All code must be documented with docstrings Maintainability and community contribution Test Coverage Minimum 90% test coverage required Quality assurance and reliability Version Control Git-based development with feature branches Collaborative development process Conventions Convention Description Background Code Style Follow PEP 8 guidelines Python community standards Type Hints Use type hints throughout the code Code clarity and IDE support Commit Messages Follow conventional commits specification Clear change history Documentation Format Use AsciiDoc for all documentation Dogfooding our own tool " + "title": "Runtime View", + "text": " Table of Contents Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence Runtime View Document Processing Sequence Rule Loading Sequence Error Reporting Sequence " }, { "id": 13, + "uri": "manual/testing.html", + "menu": "manual", + "title": "Testing Guide", + "text": " Table of Contents Testing Guide Overview Running Tests Test Structure Writing Tests Test Data Continuous Integration Testing Guide Overview The AsciiDoc Linter uses Python’s unittest framework for testing. Tests are organized by rule type and functionality. Running Tests Running All Tests # From project root python run_tests.py # With coverage report coverage run -m unittest discover coverage report Running Specific Tests # Run tests for heading rules python -m unittest tests/rules/test_heading_rules.py # Run a specific test class python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule # Run a specific test method python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule.test_valid_format Test Structure Test Organization tests/ ├── __init__.py ├── rules/ │ ├── __init__.py │ ├── test_heading_rules.py │ └── test_block_rules.py ├── test_cli.py └── test_parser.py Test Classes Each rule has its own test class: class TestHeadingFormatRule(unittest.TestCase): def setUp(self): self.rule = HeadingFormatRule() def test_valid_format(self): content = \"\"\" = Valid Heading == Another Valid \"\"\" findings = self.rule.check(content) self.assertEqual(len(findings), 0) Writing Tests Test Guidelines Test both valid and invalid cases Include edge cases Test error messages Test severity levels Test rule configurations Example Test Pattern Arrange: Set up test data Act: Execute the code Assert: Verify results def test_invalid_format(self): # Arrange content = \"=invalid heading\" # Act findings = self.rule.check(content) # Assert self.assertEqual(len(findings), 2) self.assertEqual(findings[0].severity, Severity.ERROR) Test Data Sample Documents Create realistic test documents Cover various scenarios Include complex cases Document test case purpose Test Fixtures Use setUp and tearDown Share common test data Clean up after tests Continuous Integration GitHub Actions name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Run Tests run: python run_tests.py Coverage Requirements Aim for 90%+ coverage Cover all code paths Include error conditions Test edge cases " +}, + +{ + "id": 14, + "uri": "manual/development.html", + "menu": "manual", + "title": "Development Guide", + "text": " Table of Contents Development Guide Setting Up Development Environment Project Structure Adding New Rules Code Style Pull Request Process Release Process Development Guide Setting Up Development Environment Clone the Repository git clone https://github.com/yourusername/asciidoc-linter.git cd asciidoc-linter Create Virtual Environment python -m venv venv source venv/bin/activate # On Windows: venv\\Scripts\\activate pip install -e . Project Structure asciidoc-linter/ ├── asciidoc_linter/ # Main package │ ├── __init__.py │ ├── cli.py # Command line interface │ ├── rules.py # Base rule classes │ ├── heading_rules.py # Heading-specific rules │ ├── parser.py # AsciiDoc parser │ └── reporter.py # Output formatters ├── tests/ # Test files │ └── rules/ │ └── test_heading_rules.py ├── docs/ # Documentation └── README.adoc Adding New Rules Rule Implementation Steps Create a new rule class: from .rules import Rule, Finding, Severity, Position class MyNewRule(Rule): def __init__(self): super().__init__() self.id = \"NEW001\" @property def description(self) -> str: return \"Description of what this rule checks\" def check(self, content: str) -> List[Finding]: findings = [] # Implementation here return findings Add tests for the rule Register the rule in the linter Update documentation Rule Guidelines Clear rule IDs and descriptions Meaningful error messages Proper severity levels Contextual information in findings Code Style Python Guidelines Follow PEP 8 Use type hints Write docstrings Keep functions focused Documentation Guidelines Use AsciiDoc format Include examples Explain error messages Document configuration options Pull Request Process Create feature branch Implement changes Add/update tests Update documentation Submit PR Release Process Update version number Update changelog Run full test suite Create release notes Tag release Build and publish " +}, + +{ + "id": 15, + "uri": "manual/usage.html", + "menu": "manual", + "title": "Usage Guide", + "text": " Table of Contents Usage Guide Command Line Interface Configuration Output Formats Integration Best Practices Troubleshooting Usage Guide Command Line Interface Basic Usage # Check a single file asciidoc-lint document.adoc # Check multiple files asciidoc-lint doc1.adoc doc2.adoc # Check with specific output format asciidoc-lint --format json document.adoc # Use specific configuration asciidoc-lint --config my-config.yml document.adoc Command Line Options Option Default Description --format console Output format (console, json, html) --config None Path to configuration file --verbose False Enable verbose output --quiet False Suppress non-error output Configuration Configuration File # .asciidoc-lint.yml rules: HEAD001: enabled: true severity: error HEAD002: enabled: true severity: warning Rule Configuration Enable/disable rules Set severity levels Configure rule-specific options Set file patterns Output Formats Console Output document.adoc:15 ERROR: Heading level skipped document.adoc:23 WARNING: Heading should start with uppercase JSON Output { \"findings\": [ { \"rule\": \"HEAD001\", \"severity\": \"error\", \"message\": \"Heading level skipped\", \"line\": 15 } ] } HTML Report Generates a detailed HTML report with: Summary statistics Detailed findings Source context Rule explanations Integration Git Pre-commit Hook #!/bin/sh files=$(git diff --cached --name-only --diff-filter=ACM | grep '.adoc$') if [ -n \"$files\" ]; then asciidoc-lint $files fi CI/CD Integration GitHub Actions Example name: Lint AsciiDoc on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Lint Documentation run: | pip install asciidoc-linter asciidoc-lint docs/ Best Practices Document Organization Use consistent heading levels Add blank lines around blocks Use proper formatting Include alt text for images Error Resolution Table 1. Common Issues and Solutions Issue Solution Skipped heading level Ensure heading levels increment by one Missing space after = Add space after heading markers Multiple top-level headings Use only one level-1 heading per document Troubleshooting Common Problems Configuration file not found Rule conflicts Performance issues False positives Debug Mode # Enable debug output asciidoc-lint --debug document.adoc # Show rule processing details asciidoc-lint --verbose document.adoc " +}, + +{ + "id": 16, + "uri": "manual/introduction.html", + "menu": "manual", + "title": "Introduction", + "text": " Table of Contents Introduction About the Project Key Features Project Goals Technical Overview Getting Started Introduction About the Project AsciiDoc Linter is a Python-based tool designed to help maintain high-quality AsciiDoc documentation. It checks your AsciiDoc files for common issues and style violations, helping teams maintain consistent documentation standards. Key Features Heading structure validation Format checking Style consistency enforcement Multiple output formats Configurable rules Project Goals Improve documentation quality Enforce consistent styling Reduce review effort Catch common mistakes early Support documentation as code Technical Overview Table 1. Technology Stack Component Description Language Python 3.8+ Testing unittest framework Documentation AsciiDoc Configuration YAML/JSON (planned) Getting Started Prerequisites Python 3.8 or higher pip (Python package manager) Git (for development) Quick Start # Install the package pip install asciidoc-linter # Run a basic check asciidoc-lint your-document.adoc # Get help asciidoc-lint --help " +}, + +{ + "id": 17, + "uri": "manual/index.html", + "menu": "manual", + "title": "AsciiDoc Linter Manual", + "text": " Table of Contents AsciiDoc Linter Manual Introduction Development Guide Testing Guide Usage Guide Rule Reference Title AsciiDoc Linter Manual Introduction About the Project AsciiDoc Linter is a Python-based tool designed to help maintain high-quality AsciiDoc documentation. It checks your AsciiDoc files for common issues and style violations, helping teams maintain consistent documentation standards. Key Features Heading structure validation Format checking Style consistency enforcement Multiple output formats Configurable rules Project Goals Improve documentation quality Enforce consistent styling Reduce review effort Catch common mistakes early Support documentation as code Technical Overview Table 1. Technology Stack Component Description Language Python 3.8+ Testing unittest framework Documentation AsciiDoc Configuration YAML/JSON (planned) Getting Started Prerequisites Python 3.8 or higher pip (Python package manager) Git (for development) Quick Start # Install the package pip install asciidoc-linter # Run a basic check asciidoc-lint your-document.adoc # Get help asciidoc-lint --help Development Guide Setting Up Development Environment Clone the Repository git clone https://github.com/yourusername/asciidoc-linter.git cd asciidoc-linter Create Virtual Environment python -m venv venv source venv/bin/activate # On Windows: venv\\Scripts\\activate pip install -e . Project Structure asciidoc-linter/ ├── asciidoc_linter/ # Main package │ ├── __init__.py │ ├── cli.py # Command line interface │ ├── rules.py # Base rule classes │ ├── heading_rules.py # Heading-specific rules │ ├── parser.py # AsciiDoc parser │ └── reporter.py # Output formatters ├── tests/ # Test files │ └── rules/ │ └── test_heading_rules.py ├── docs/ # Documentation └── README.adoc Adding New Rules Rule Implementation Steps Create a new rule class: from .rules import Rule, Finding, Severity, Position class MyNewRule(Rule): def __init__(self): super().__init__() self.id = \"NEW001\" @property def description(self) -> str: return \"Description of what this rule checks\" def check(self, content: str) -> List[Finding]: findings = [] # Implementation here return findings Add tests for the rule Register the rule in the linter Update documentation Rule Guidelines Clear rule IDs and descriptions Meaningful error messages Proper severity levels Contextual information in findings Code Style Python Guidelines Follow PEP 8 Use type hints Write docstrings Keep functions focused Documentation Guidelines Use AsciiDoc format Include examples Explain error messages Document configuration options Pull Request Process Create feature branch Implement changes Add/update tests Update documentation Submit PR Release Process Update version number Update changelog Run full test suite Create release notes Tag release Build and publish Testing Guide Overview The AsciiDoc Linter uses Python’s unittest framework for testing. Tests are organized by rule type and functionality. Running Tests Running All Tests # From project root python run_tests.py # With coverage report coverage run -m unittest discover coverage report Running Specific Tests # Run tests for heading rules python -m unittest tests/rules/test_heading_rules.py # Run a specific test class python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule # Run a specific test method python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule.test_valid_format Test Structure Test Organization tests/ ├── __init__.py ├── rules/ │ ├── __init__.py │ ├── test_heading_rules.py │ └── test_block_rules.py ├── test_cli.py └── test_parser.py Test Classes Each rule has its own test class: class TestHeadingFormatRule(unittest.TestCase): def setUp(self): self.rule = HeadingFormatRule() def test_valid_format(self): content = \"\"\" = Valid Heading == Another Valid \"\"\" findings = self.rule.check(content) self.assertEqual(len(findings), 0) Writing Tests Test Guidelines Test both valid and invalid cases Include edge cases Test error messages Test severity levels Test rule configurations Example Test Pattern Arrange: Set up test data Act: Execute the code Assert: Verify results def test_invalid_format(self): # Arrange content = \"=invalid heading\" # Act findings = self.rule.check(content) # Assert self.assertEqual(len(findings), 2) self.assertEqual(findings[0].severity, Severity.ERROR) Test Data Sample Documents Create realistic test documents Cover various scenarios Include complex cases Document test case purpose Test Fixtures Use setUp and tearDown Share common test data Clean up after tests Continuous Integration GitHub Actions name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Run Tests run: python run_tests.py Coverage Requirements Aim for 90%+ coverage Cover all code paths Include error conditions Test edge cases Usage Guide Command Line Interface Basic Usage # Check a single file asciidoc-lint document.adoc # Check multiple files asciidoc-lint doc1.adoc doc2.adoc # Check with specific output format asciidoc-lint --format json document.adoc # Use specific configuration asciidoc-lint --config my-config.yml document.adoc Command Line Options Option Default Description --format console Output format (console, json, html) --config None Path to configuration file --verbose False Enable verbose output --quiet False Suppress non-error output Configuration Configuration File # .asciidoc-lint.yml rules: HEAD001: enabled: true severity: error HEAD002: enabled: true severity: warning Rule Configuration Enable/disable rules Set severity levels Configure rule-specific options Set file patterns Output Formats Console Output document.adoc:15 ERROR: Heading level skipped document.adoc:23 WARNING: Heading should start with uppercase JSON Output { \"findings\": [ { \"rule\": \"HEAD001\", \"severity\": \"error\", \"message\": \"Heading level skipped\", \"line\": 15 } ] } HTML Report Generates a detailed HTML report with: Summary statistics Detailed findings Source context Rule explanations Integration Git Pre-commit Hook #!/bin/sh files=$(git diff --cached --name-only --diff-filter=ACM | grep '.adoc$') if [ -n \"$files\" ]; then asciidoc-lint $files fi CI/CD Integration GitHub Actions Example name: Lint AsciiDoc on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Lint Documentation run: | pip install asciidoc-linter asciidoc-lint docs/ Best Practices Document Organization Use consistent heading levels Add blank lines around blocks Use proper formatting Include alt text for images Error Resolution Table 2. Common Issues and Solutions Issue Solution Skipped heading level Ensure heading levels increment by one Missing space after = Add space after heading markers Multiple top-level headings Use only one level-1 heading per document Troubleshooting Common Problems Configuration file not found Rule conflicts Performance issues False positives Debug Mode # Enable debug output asciidoc-lint --debug document.adoc # Show rule processing details asciidoc-lint --verbose document.adoc Rule Reference Heading Rules HEAD001: Heading Incrementation Ensures that heading levels are properly incremented and no levels are skipped. Valid Example == Level 1 === Level 2 ==== Level 3 Invalid Example == Level 1 ==== Level 3 # Error: Skipped level 2 Table 3. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level HEAD002: Heading Format Checks heading format for proper spacing and capitalization. Valid Example == Title === Section ==== Subsection Invalid Examples =Title # Error: Missing space == title # Warning: Lowercase ==Section # Error: Missing space Table 4. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level check_case true Check for proper capitalization HEAD003: Multiple Top-Level Headings Ensures there is only one top-level heading per document. Valid Example == Document Title === Section 1 === Section 2 Invalid Example == First Title === Section 1 == Second Title # Error: Multiple top-level headings Table 5. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level Planned Rules BLOCK001: Block Termination Checks for properly terminated blocks. Valid Example [source,python] def hello(): print(\"Hello\") Invalid Example [source,python] def hello(): print(\"Hello\") # Missing block termination ==== WS001: Whitespace [.planned] Ensures proper spacing around elements. .Valid Example [source,asciidoc] Title Section Some content. code === Rule Development ==== Creating New Rules 1. Extend the base Rule class 2. Implement check method 3. Add tests 4. Document the rule ==== Rule Guidelines * Clear error messages * Meaningful context * Configurable options * Performance conscious === Rule Categories ==== Current Categories * Heading Rules (HEAD*) * Block Rules (BLOCK*) * Whitespace Rules (WS*) * Format Rules (FMT*) ==== Planned Categories * Table Rules (TABLE*) * Image Rules (IMG*) * Link Rules (LINK*) * Reference Rules (REF*) :leveloffset!: " +}, + +{ + "id": 18, + "uri": "manual/rules.html", + "menu": "manual", + "title": "Rule Reference", + "text": " Table of Contents Rule Reference Heading Rules Planned Rules Title Section Rule Reference Heading Rules HEAD001: Heading Incrementation Ensures that heading levels are properly incremented and no levels are skipped. Valid Example == Level 1 === Level 2 ==== Level 3 Invalid Example == Level 1 ==== Level 3 # Error: Skipped level 2 Table 1. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level HEAD002: Heading Format Checks heading format for proper spacing and capitalization. Valid Example == Title === Section ==== Subsection Invalid Examples =Title # Error: Missing space == title # Warning: Lowercase ==Section # Error: Missing space Table 2. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level check_case true Check for proper capitalization HEAD003: Multiple Top-Level Headings Ensures there is only one top-level heading per document. Valid Example == Document Title === Section 1 === Section 2 Invalid Example == First Title === Section 1 == Second Title # Error: Multiple top-level headings Table 3. Configuration Options Option Default Description enabled true Enable/disable rule severity error Rule severity level Planned Rules BLOCK001: Block Termination Checks for properly terminated blocks. Valid Example [source,python] def hello(): print(\"Hello\") Invalid Example [source,python] def hello(): print(\"Hello\") # Missing block termination ==== WS001: Whitespace [.planned] Ensures proper spacing around elements. .Valid Example [source,asciidoc] Title Section Some content. code === Rule Development ==== Creating New Rules 1. Extend the base Rule class 2. Implement check method 3. Add tests 4. Document the rule ==== Rule Guidelines * Clear error messages * Meaningful context * Configurable options * Performance conscious === Rule Categories ==== Current Categories * Heading Rules (HEAD*) * Block Rules (BLOCK*) * Whitespace Rules (WS*) * Format Rules (FMT*) ==== Planned Categories * Table Rules (TABLE*) * Image Rules (IMG*) * Link Rules (LINK*) * Reference Rules (REF*) " +}, + +{ + "id": 19, "uri": "search.html", "menu": "-", "title": "search", @@ -113,7 +161,7 @@ var documents = [ }, { - "id": 14, + "id": 20, "uri": "lunrjsindex.html", "menu": "-", "title": "null", diff --git a/manual/development.adoc.meta b/manual/development.adoc.meta new file mode 100755 index 0000000..df869c1 --- /dev/null +++ b/manual/development.adoc.meta @@ -0,0 +1 @@ +Development guide \ No newline at end of file diff --git a/manual/development.html b/manual/development.html new file mode 100644 index 0000000..9f96467 --- /dev/null +++ b/manual/development.html @@ -0,0 +1,727 @@ + + + + + + + + + + + + Development Guide + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    +
    +
    + + +
    + + + + + +
    + + + +
    +
    +
    +
    + + + Improve this doc + + + Create an issue + + + +
    + + + + + + +
    +
    +
    + + + +
    +

    + +

    +

    Development Guide

    +
    +
    +

    Setting Up Development Environment

    +
    +

    Clone the Repository

    +
    +
    +
    git clone https://github.com/yourusername/asciidoc-linter.git
+cd asciidoc-linter
    +
    +
    +
    +
    +

    Create Virtual Environment

    +
    +
    +
    python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
    +
    +
    +
    +
    +
    +

    Project Structure

    +
    +
    +
    asciidoc-linter/
+├── asciidoc_linter/       # Main package
+│   ├── __init__.py
+│   ├── cli.py            # Command line interface
+│   ├── rules.py          # Base rule classes
+│   ├── heading_rules.py  # Heading-specific rules
+│   ├── parser.py         # AsciiDoc parser
+│   └── reporter.py       # Output formatters
+├── tests/                # Test files
+│   └── rules/
+│       └── test_heading_rules.py
+├── docs/                 # Documentation
+└── README.adoc
    +
    +
    +
    +
    +

    Adding New Rules

    +
    +

    Rule Implementation Steps

    +
    +
      +
    1. +

      Create a new rule class:

      +
      +
      +
      from .rules import Rule, Finding, Severity, Position
+
+class MyNewRule(Rule):
+    def __init__(self):
+        super().__init__()
+        self.id = "NEW001"
+
+    @property
+    def description(self) -> str:
+        return "Description of what this rule checks"
+
+    def check(self, content: str) -> List[Finding]:
+        findings = []
+        # Implementation here
+        return findings
      +
      +
      +
      2. +
    2. +

      Add tests for the rule

      +
      3. +
    3. +

      Register the rule in the linter

      +
      4. +
    4. +

      Update documentation

      +
      5. +
    +
    +
    +
    +

    Rule Guidelines

    +
    +
      +
    • +

      Clear rule IDs and descriptions

      +
      • +
    • +

      Meaningful error messages

      +
      • +
    • +

      Proper severity levels

      +
      • +
    • +

      Contextual information in findings

      +
      • +
    +
    +
    +
    +
    +

    Code Style

    +
    +

    Python Guidelines

    +
    +
      +
    • +

      Follow PEP 8

      +
      • +
    • +

      Use type hints

      +
      • +
    • +

      Write docstrings

      +
      • +
    • +

      Keep functions focused

      +
      • +
    +
    +
    +
    +

    Documentation Guidelines

    +
    +
      +
    • +

      Use AsciiDoc format

      +
      • +
    • +

      Include examples

      +
      • +
    • +

      Explain error messages

      +
      • +
    • +

      Document configuration options

      +
      • +
    +
    +
    +
    +
    +

    Pull Request Process

    +
    +
      +
    1. +

      Create feature branch

      +
      2. +
    2. +

      Implement changes

      +
      3. +
    3. +

      Add/update tests

      +
      4. +
    4. +

      Update documentation

      +
      5. +
    5. +

      Submit PR

      +
      6. +
    +
    +
    +
    +

    Release Process

    +
    +
      +
    1. +

      Update version number

      +
      2. +
    2. +

      Update changelog

      +
      3. +
    3. +

      Run full test suite

      +
      4. +
    4. +

      Create release notes

      +
      5. +
    5. +

      Tag release

      +
      6. +
    6. +

      Build and publish

      +
      7. +
    +
    +
    +
    +
    +

    + + + +
    + + + + + + +
    + + + +
    + + +
    + + +
    + +
    +
    + + + + + + + + + + + + + + + + + + + + diff --git a/manual/index.adoc.meta b/manual/index.adoc.meta new file mode 100755 index 0000000..22930bd --- /dev/null +++ b/manual/index.adoc.meta @@ -0,0 +1 @@ +Main documentation file that includes all other parts \ No newline at end of file diff --git a/manual/index.html b/manual/index.html new file mode 100644 index 0000000..b5df5a0 --- /dev/null +++ b/manual/index.html @@ -0,0 +1,1586 @@ + + + + + + + + + + + + AsciiDoc Linter Manual + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    +
    +
    + + +
    + + + + + +
    + + + +
    +
    +
    +
    + + + Improve this doc + + + Create an issue + + + +
    + + + + + + +
    +
    +
    + + + +
    +

    + +

    +

    AsciiDoc Linter Manual

    +
    +
    +

    Introduction

    +
    +

    About the Project

    +
    +

    AsciiDoc Linter is a Python-based tool designed to help maintain high-quality AsciiDoc documentation. It checks your AsciiDoc files for common issues and style violations, helping teams maintain consistent documentation standards.

    +
    +
    +
    +

    Key Features

    +
    +
      +
    • +

      Heading structure validation

      +
      • +
    • +

      Format checking

      +
      • +
    • +

      Style consistency enforcement

      +
      • +
    • +

      Multiple output formats

      +
      • +
    • +

      Configurable rules

      +
      • +
    +
    +
    +
    +

    Project Goals

    +
    +
      +
    • +

      Improve documentation quality

      +
      • +
    • +

      Enforce consistent styling

      +
      • +
    • +

      Reduce review effort

      +
      • +
    • +

      Catch common mistakes early

      +
      • +
    • +

      Support documentation as code

      +
      • +
    +
    +
    +
    +

    Technical Overview

    + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 1. Technology Stack
    ComponentDescription

    Language

    Python 3.8+

    Testing

    unittest framework

    Documentation

    AsciiDoc

    Configuration

    YAML/JSON (planned)

    +
    +
    +

    Getting Started

    +
    +
    Prerequisites
    +
    +
      +
    • +

      Python 3.8 or higher

      +
      • +
    • +

      pip (Python package manager)

      +
      • +
    • +

      Git (for development)

      +
      • +
    +
    +
    +
    +
    Quick Start
    +
    +
    +
    # Install the package
+pip install asciidoc-linter
+
+# Run a basic check
+asciidoc-lint your-document.adoc
+
+# Get help
+asciidoc-lint --help
    +
    +
    +
    +
    +
    +
    +

    Development Guide

    +
    +

    Setting Up Development Environment

    +
    +
    Clone the Repository
    +
    +
    +
    git clone https://github.com/yourusername/asciidoc-linter.git
+cd asciidoc-linter
    +
    +
    +
    +
    +
    Create Virtual Environment
    +
    +
    +
    python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
    +
    +
    +
    +
    +
    +

    Project Structure

    +
    +
    +
    asciidoc-linter/
+├── asciidoc_linter/       # Main package
+│   ├── __init__.py
+│   ├── cli.py            # Command line interface
+│   ├── rules.py          # Base rule classes
+│   ├── heading_rules.py  # Heading-specific rules
+│   ├── parser.py         # AsciiDoc parser
+│   └── reporter.py       # Output formatters
+├── tests/                # Test files
+│   └── rules/
+│       └── test_heading_rules.py
+├── docs/                 # Documentation
+└── README.adoc
    +
    +
    +
    +
    +

    Adding New Rules

    +
    +
    Rule Implementation Steps
    +
    +
      +
    1. +

      Create a new rule class:

      +
      +
      +
      from .rules import Rule, Finding, Severity, Position
+
+class MyNewRule(Rule):
+    def __init__(self):
+        super().__init__()
+        self.id = "NEW001"
+
+    @property
+    def description(self) -> str:
+        return "Description of what this rule checks"
+
+    def check(self, content: str) -> List[Finding]:
+        findings = []
+        # Implementation here
+        return findings
      +
      +
      +
      2. +
    2. +

      Add tests for the rule

      +
      3. +
    3. +

      Register the rule in the linter

      +
      4. +
    4. +

      Update documentation

      +
      5. +
    +
    +
    +
    +
    Rule Guidelines
    +
    +
      +
    • +

      Clear rule IDs and descriptions

      +
      • +
    • +

      Meaningful error messages

      +
      • +
    • +

      Proper severity levels

      +
      • +
    • +

      Contextual information in findings

      +
      • +
    +
    +
    +
    +
    +

    Code Style

    +
    +
    Python Guidelines
    +
    +
      +
    • +

      Follow PEP 8

      +
      • +
    • +

      Use type hints

      +
      • +
    • +

      Write docstrings

      +
      • +
    • +

      Keep functions focused

      +
      • +
    +
    +
    +
    +
    Documentation Guidelines
    +
    +
      +
    • +

      Use AsciiDoc format

      +
      • +
    • +

      Include examples

      +
      • +
    • +

      Explain error messages

      +
      • +
    • +

      Document configuration options

      +
      • +
    +
    +
    +
    +
    +

    Pull Request Process

    +
    +
      +
    1. +

      Create feature branch

      +
      2. +
    2. +

      Implement changes

      +
      3. +
    3. +

      Add/update tests

      +
      4. +
    4. +

      Update documentation

      +
      5. +
    5. +

      Submit PR

      +
      6. +
    +
    +
    +
    +

    Release Process

    +
    +
      +
    1. +

      Update version number

      +
      2. +
    2. +

      Update changelog

      +
      3. +
    3. +

      Run full test suite

      +
      4. +
    4. +

      Create release notes

      +
      5. +
    5. +

      Tag release

      +
      6. +
    6. +

      Build and publish

      +
      7. +
    +
    +
    +
    +
    +

    Testing Guide

    +
    +

    Overview

    +
    +

    The AsciiDoc Linter uses Python’s unittest framework for testing. Tests are organized by rule type and functionality.

    +
    +
    +
    +

    Running Tests

    +
    +
    Running All Tests
    +
    +
    +
    # From project root
+python run_tests.py
+
+# With coverage report
+coverage run -m unittest discover
+coverage report
    +
    +
    +
    +
    +
    Running Specific Tests
    +
    +
    +
    # Run tests for heading rules
+python -m unittest tests/rules/test_heading_rules.py
+
+# Run a specific test class
+python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule
+
+# Run a specific test method
+python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule.test_valid_format
    +
    +
    +
    +
    +
    +

    Test Structure

    +
    +
    Test Organization
    +
    +
    +
    tests/
+├── __init__.py
+├── rules/
+│   ├── __init__.py
+│   ├── test_heading_rules.py
+│   └── test_block_rules.py
+├── test_cli.py
+└── test_parser.py
    +
    +
    +
    +
    +
    Test Classes
    +
    +

    Each rule has its own test class:

    +
    +
    +
    +
    class TestHeadingFormatRule(unittest.TestCase):
+    def setUp(self):
+        self.rule = HeadingFormatRule()
+
+    def test_valid_format(self):
+        content = """
+        = Valid Heading
+        == Another Valid
+        """
+        findings = self.rule.check(content)
+        self.assertEqual(len(findings), 0)
    +
    +
    +
    +
    +
    +

    Writing Tests

    +
    +
    Test Guidelines
    +
    +
      +
    • +

      Test both valid and invalid cases

      +
      • +
    • +

      Include edge cases

      +
      • +
    • +

      Test error messages

      +
      • +
    • +

      Test severity levels

      +
      • +
    • +

      Test rule configurations

      +
      • +
    +
    +
    +
    +
    Example Test Pattern
    +
    +
      +
    1. +

      Arrange: Set up test data

      +
      2. +
    2. +

      Act: Execute the code

      +
      3. +
    3. +

      Assert: Verify results

      +
      4. +
    +
    +
    +
    +
    def test_invalid_format(self):
+    # Arrange
+    content = "=invalid heading"
+
+    # Act
+    findings = self.rule.check(content)
+
+    # Assert
+    self.assertEqual(len(findings), 2)
+    self.assertEqual(findings[0].severity, Severity.ERROR)
    +
    +
    +
    +
    +
    +

    Test Data

    +
    +
    Sample Documents
    +
    +
      +
    • +

      Create realistic test documents

      +
      • +
    • +

      Cover various scenarios

      +
      • +
    • +

      Include complex cases

      +
      • +
    • +

      Document test case purpose

      +
      • +
    +
    +
    +
    +
    Test Fixtures
    +
    +
      +
    • +

      Use setUp and tearDown

      +
      • +
    • +

      Share common test data

      +
      • +
    • +

      Clean up after tests

      +
      • +
    +
    +
    +
    +
    +

    Continuous Integration

    +
    +
    GitHub Actions
    +
    +
    +
    name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run Tests
+        run: python run_tests.py
    +
    +
    +
    +
    +
    Coverage Requirements
    +
    +
      +
    • +

      Aim for 90%+ coverage

      +
      • +
    • +

      Cover all code paths

      +
      • +
    • +

      Include error conditions

      +
      • +
    • +

      Test edge cases

      +
      • +
    +
    +
    +
    +
    +
    +

    Usage Guide

    +
    +

    Command Line Interface

    +
    +
    Basic Usage
    +
    +
    +
    # Check a single file
+asciidoc-lint document.adoc
+
+# Check multiple files
+asciidoc-lint doc1.adoc doc2.adoc
+
+# Check with specific output format
+asciidoc-lint --format json document.adoc
+
+# Use specific configuration
+asciidoc-lint --config my-config.yml document.adoc
    +
    +
    +
    +
    +
    Command Line Options
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionDefaultDescription

    --format

    console

    Output format (console, json, html)

    --config

    None

    Path to configuration file

    --verbose

    False

    Enable verbose output

    --quiet

    False

    Suppress non-error output

    +
    +
    +
    +

    Configuration

    +
    +
    Configuration File
    +
    +
    +
    # .asciidoc-lint.yml
+rules:
+  HEAD001:
+    enabled: true
+    severity: error
+  HEAD002:
+    enabled: true
+    severity: warning
    +
    +
    +
    +
    +
    Rule Configuration
    +
    +
      +
    • +

      Enable/disable rules

      +
      • +
    • +

      Set severity levels

      +
      • +
    • +

      Configure rule-specific options

      +
      • +
    • +

      Set file patterns

      +
      • +
    +
    +
    +
    +
    +

    Output Formats

    +
    +
    Console Output
    +
    +
    +
    document.adoc:15 ERROR: Heading level skipped
+document.adoc:23 WARNING: Heading should start with uppercase
    +
    +
    +
    +
    +
    JSON Output
    +
    +
    +
    {
+  "findings": [
+    {
+      "rule": "HEAD001",
+      "severity": "error",
+      "message": "Heading level skipped",
+      "line": 15
+    }
+  ]
+}
    +
    +
    +
    +
    +
    HTML Report
    +
    +

    Generates a detailed HTML report with:

    +
    +
    +
      +
    • +

      Summary statistics

      +
      • +
    • +

      Detailed findings

      +
      • +
    • +

      Source context

      +
      • +
    • +

      Rule explanations

      +
      • +
    +
    +
    +
    +
    +

    Integration

    +
    +
    Git Pre-commit Hook
    +
    +
    +
    #!/bin/sh
+files=$(git diff --cached --name-only --diff-filter=ACM | grep '.adoc$')
+if [ -n "$files" ]; then
+    asciidoc-lint $files
+fi
    +
    +
    +
    +
    +
    CI/CD Integration
    +
    +
    GitHub Actions Example
    +
    +
    name: Lint AsciiDoc
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Lint Documentation
+        run: |
+          pip install asciidoc-linter
+          asciidoc-lint docs/
    +
    +
    +
    +
    +
    +

    Best Practices

    +
    +
    Document Organization
    +
    +
      +
    • +

      Use consistent heading levels

      +
      • +
    • +

      Add blank lines around blocks

      +
      • +
    • +

      Use proper formatting

      +
      • +
    • +

      Include alt text for images

      +
      • +
    +
    +
    +
    +
    Error Resolution
    + + ++++ + + + + + + + + + + + + + + + + + + + + +
    Table 2. Common Issues and Solutions
    IssueSolution

    Skipped heading level

    Ensure heading levels increment by one

    Missing space after =

    Add space after heading markers

    Multiple top-level headings

    Use only one level-1 heading per document

    +
    +
    +
    +

    Troubleshooting

    +
    +
    Common Problems
    +
    +
      +
    • +

      Configuration file not found

      +
      • +
    • +

      Rule conflicts

      +
      • +
    • +

      Performance issues

      +
      • +
    • +

      False positives

      +
      • +
    +
    +
    +
    +
    Debug Mode
    +
    +
    +
    # Enable debug output
+asciidoc-lint --debug document.adoc
+
+# Show rule processing details
+asciidoc-lint --verbose document.adoc
    +
    +
    +
    +
    +
    +
    +

    Rule Reference

    +
    +

    Heading Rules

    +
    +
    HEAD001: Heading Incrementation
    +
    +

    Ensures that heading levels are properly incremented and no levels are skipped.

    +
    +
    +
    Valid Example
    +
    +
    == Level 1
+=== Level 2
+==== Level 3
    +
    +
    +
    +
    Invalid Example
    +
    +
    == Level 1
+==== Level 3  # Error: Skipped level 2
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + +
    Table 3. Configuration Options
    OptionDefaultDescription

    enabled

    true

    Enable/disable rule

    severity

    error

    Rule severity level

    +
    +
    +
    HEAD002: Heading Format
    +
    +

    Checks heading format for proper spacing and capitalization.

    +
    +
    +
    Valid Example
    +
    +
    == Title
+=== Section
+==== Subsection
    +
    +
    +
    +
    Invalid Examples
    +
    +
    =Title        # Error: Missing space
+== title       # Warning: Lowercase
+==Section     # Error: Missing space
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 4. Configuration Options
    OptionDefaultDescription

    enabled

    true

    Enable/disable rule

    severity

    error

    Rule severity level

    check_case

    true

    Check for proper capitalization

    +
    +
    +
    HEAD003: Multiple Top-Level Headings
    +
    +

    Ensures there is only one top-level heading per document.

    +
    +
    +
    Valid Example
    +
    +
    == Document Title
+=== Section 1
+=== Section 2
    +
    +
    +
    +
    Invalid Example
    +
    +
    == First Title
+=== Section 1
+== Second Title  # Error: Multiple top-level headings
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + +
    Table 5. Configuration Options
    OptionDefaultDescription

    enabled

    true

    Enable/disable rule

    severity

    error

    Rule severity level

    +
    +
    +
    +

    Planned Rules

    +
    +
    BLOCK001: Block Termination
    +
    +

    Checks for properly terminated blocks.

    +
    +
    +
    Valid Example
    +
    +
    [source,python]
    +
    +
    +
    +

    def hello(): + print("Hello")

    +
    +
    +
    +
    
+
    
+
    
+
    
+
    Invalid Example
    
+
    
+
    [source,python]
    
+
    
+
    
+
    
+
    def hello():
+    print("Hello")
+# Missing block termination
    
+
    
+
    
+
    
+
    ==== WS001: Whitespace
+
+[.planned]
+Ensures proper spacing around elements.
+
+.Valid Example
+[source,asciidoc]
    
+
    
+
    
+
    
+
    
+
    
+
    
+
    Title
    
+
    
+
    Section
    
+
    
+
    Some content.
    
+
    
+
    
+
    
+
    code
    
+
    
+
    
+
    
+
    
+
    === Rule Development
+
+==== Creating New Rules
+
+1. Extend the base Rule class
+2. Implement check method
+3. Add tests
+4. Document the rule
+
+==== Rule Guidelines
+
+* Clear error messages
+* Meaningful context
+* Configurable options
+* Performance conscious
+
+=== Rule Categories
+
+==== Current Categories
+
+* Heading Rules (HEAD*)
+* Block Rules (BLOCK*)
+* Whitespace Rules (WS*)
+* Format Rules (FMT*)
+
+==== Planned Categories
+
+* Table Rules (TABLE*)
+* Image Rules (IMG*)
+* Link Rules (LINK*)
+* Reference Rules (REF*)
+
+:leveloffset!:
    
+
    
+
    
+
    
+
    
+
    
+
    
+        
    
+
+        
+
+
    
+    
+    
+    
+    
+    
+    
+
    
+
+
+
+        
    
+
+        
+    
    
+
+
+			
    
+
+		
    
+	
    
+
+
+	
+    
+
+    
+
+    
+    
+
+
+    
+    
+    
+    
+    
+
+
+
+
diff --git a/manual/introduction.adoc.meta b/manual/introduction.adoc.meta
new file mode 100755
index 0000000..8e38592
--- /dev/null
+++ b/manual/introduction.adoc.meta
@@ -0,0 +1 @@
+Introduction to the project
\ No newline at end of file
diff --git a/manual/introduction.html b/manual/introduction.html
new file mode 100644
index 0000000..0ddfc92
--- /dev/null
+++ b/manual/introduction.html
@@ -0,0 +1,654 @@
+
+
+
+    
+    
+    
+
+    
+    
+    
+
+    Introduction
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+
+    
+
+    
+    
+    
+
+
+
+
    
+	
+
+
+
    
+
    
+	
    
+		
    
+			
    
+				
    
+					
+
+        
    
+
+            
+
+
+            
+        
    
+
+        
+
+				
    
+			
    
+			
    
+				
    
+					
+
+         Improve this doc
+
+
+         Create an issue
+
+        
+
+        
    
+
+        
+
+
+
+
+				
    
+			
    
+			
    
+				    
+
+
+    
    
+        
    
+            
+
    
+
    Introduction
    
+
    
+
    
+
    About the Project
    
+
    
+
    AsciiDoc Linter is a Python-based tool designed to help maintain high-quality AsciiDoc documentation. It checks your AsciiDoc files for common issues and style violations, helping teams maintain consistent documentation standards.
    
+
    
+
    
+
    
+
    Key Features
    
+
    
+
      
+
    • 
+
      Heading structure validation
      
+
      • 
+
    • 
+
      Format checking
      
+
      • 
+
    • 
+
      Style consistency enforcement
      
+
      • 
+
    • 
+
      Multiple output formats
      
+
      • 
+
    • 
+
      Configurable rules
      
+
      • 
+
    
+
    
+
    
+
    
+
    Project Goals
    
+
    
+
      
+
    • 
+
      Improve documentation quality
      
+
      • 
+
    • 
+
      Enforce consistent styling
      
+
      • 
+
    • 
+
      Reduce review effort
      
+
      • 
+
    • 
+
      Catch common mistakes early
      
+
      • 
+
    • 
+
      Support documentation as code
      
+
      • 
+
    
+
    
+
    
+
    
+
    Technical Overview
    
+
+
++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Table 1. Technology Stack



    ComponentDescription
    Language
    Python 3.8+
    Testing
    unittest framework
    Documentation
    AsciiDoc
    Configuration
    YAML/JSON (planned)
    
+
    
+
    
+
    Getting Started
    
+
    
+
    Prerequisites
    
+
    
+
      
+
    • 
+
      Python 3.8 or higher
      
+
      • 
+
    • 
+
      pip (Python package manager)
      
+
      • 
+
    • 
+
      Git (for development)
      
+
      • 
+
    
+
    
+
    
+
    
+
    Quick Start
    
+
    
+
    
+
    # Install the package
+pip install asciidoc-linter
+
+# Run a basic check
+asciidoc-lint your-document.adoc
+
+# Get help
+asciidoc-lint --help
    
+
    
+
    
+
    
+
    
+
    
+
    
+        
    
+
+        
+
+
    
+    
+    
+    
+    
+    
+    
+
    
+
+
+
+        
    
+
+        
+    
    
+
+
+			
    
+
+		
    
+	
    
+
+
+	
+    
+
+    
+
+    
+    
+
+
+    
+    
+    
+    
+    
+
+
+
+
diff --git a/manual/rules.adoc.meta b/manual/rules.adoc.meta
new file mode 100755
index 0000000..d158f06
--- /dev/null
+++ b/manual/rules.adoc.meta
@@ -0,0 +1 @@
+Documentation of all rules
\ No newline at end of file
diff --git a/manual/rules.html b/manual/rules.html
new file mode 100644
index 0000000..96081ec
--- /dev/null
+++ b/manual/rules.html
@@ -0,0 +1,789 @@
+
+
+
+    
+    
+    
+
+    
+    
+    
+
+    Rule Reference
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+
+    
+
+    
+    
+    
+
+
+
+
    
+	
+
+
+
    
+
    
+	
    
+		
    
+			
    
+				
    
+					
+
+        
    
+
+            
+
+
+            
+        
    
+
+        
+
+				
    
+			
    
+			
    
+				
    
+					
+
+         Improve this doc
+
+
+         Create an issue
+
+        
+
+        
    
+
+        
    
+
    Table of Contents
    
+
+
    
+
+
+
+
+				
    
+			
    
+			
    
+				    
+
+
+    
    
+        
    
+            
+
    
+
    Rule Reference
    
+
    
+
    
+
    Heading Rules
    
+
    
+
    HEAD001: Heading Incrementation
    
+
    
+
    Ensures that heading levels are properly incremented and no levels are skipped.
    
+
    
+
    
+
    Valid Example
    
+
    
+
    == Level 1
+=== Level 2
+==== Level 3
    
+
    
+
    
+
    
+
    Invalid Example
    
+
    
+
    == Level 1
+==== Level 3  # Error: Skipped level 2
    
+
    
+
    
+
+
+++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Table 1. Configuration Options




    OptionDefaultDescription
    enabled
    true
    Enable/disable rule
    severity
    error
    Rule severity level
    
+
    
+
    
+
    HEAD002: Heading Format
    
+
    
+
    Checks heading format for proper spacing and capitalization.
    
+
    
+
    
+
    Valid Example
    
+
    
+
    == Title
+=== Section
+==== Subsection
    
+
    
+
    
+
    
+
    Invalid Examples
    
+
    
+
    =Title        # Error: Missing space
+== title       # Warning: Lowercase
+==Section     # Error: Missing space
    
+
    
+
    
+
+
+++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Table 2. Configuration Options




    OptionDefaultDescription
    enabled
    true
    Enable/disable rule
    severity
    error
    Rule severity level
    check_case
    true
    Check for proper capitalization
    
+
    
+
    
+
    HEAD003: Multiple Top-Level Headings
    
+
    
+
    Ensures there is only one top-level heading per document.
    
+
    
+
    
+
    Valid Example
    
+
    
+
    == Document Title
+=== Section 1
+=== Section 2
    
+
    
+
    
+
    
+
    Invalid Example
    
+
    
+
    == First Title
+=== Section 1
+== Second Title  # Error: Multiple top-level headings
    
+
    
+
    
+
+
+++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Table 3. Configuration Options




    OptionDefaultDescription
    enabled
    true
    Enable/disable rule
    severity
    error
    Rule severity level
    
+
    
+
    
+
    
+
    Planned Rules
    
+
    
+
    BLOCK001: Block Termination
    
+
    
+
    Checks for properly terminated blocks.
    
+
    
+
    
+
    Valid Example
    
+
    
+
    [source,python]
    
+
    
+
    
+
    
+
    def hello():
+    print("Hello")
    
+
    
+
    
+
    
+
    
+
    
+
    
+
    
+
    Invalid Example
    
+
    
+
    [source,python]
    
+
    
+
    
+
    
+
    def hello():
+    print("Hello")
+# Missing block termination
    
+
    
+
    
+
    
+
    ==== WS001: Whitespace
+
+[.planned]
+Ensures proper spacing around elements.
+
+.Valid Example
+[source,asciidoc]
    
+
    
+
    
+
    
+
    
+
    
+
    
+
    
+
    Title
    
+
    
+
    
+
    Section
    
+
    
+
    Some content.
    
+
    
+
    
+
    
+
    code
    
+
    
+
    
+
    
+
    
+
    === Rule Development
+
+==== Creating New Rules
+
+1. Extend the base Rule class
+2. Implement check method
+3. Add tests
+4. Document the rule
+
+==== Rule Guidelines
+
+* Clear error messages
+* Meaningful context
+* Configurable options
+* Performance conscious
+
+=== Rule Categories
+
+==== Current Categories
+
+* Heading Rules (HEAD*)
+* Block Rules (BLOCK*)
+* Whitespace Rules (WS*)
+* Format Rules (FMT*)
+
+==== Planned Categories
+
+* Table Rules (TABLE*)
+* Image Rules (IMG*)
+* Link Rules (LINK*)
+* Reference Rules (REF*)
    
+
    
+
    
+
    
+
    
+
    
+        
    
+
+        
+
+
    
+    
+    
+    
+    
+    
+    
+
    
+
+
+
+        
    
+
+        
+    
    
+
+
+			
    
+
+		
    
+	
    
+
+
+	
+    
+
+    
+
+    
+    
+
+
+    
+    
+    
+    
+    
+
+
+
+
diff --git a/manual/testing.adoc.meta b/manual/testing.adoc.meta
new file mode 100755
index 0000000..b7f4630
--- /dev/null
+++ b/manual/testing.adoc.meta
@@ -0,0 +1 @@
+Testing guide
\ No newline at end of file
diff --git a/manual/testing.html b/manual/testing.html
new file mode 100644
index 0000000..67933af
--- /dev/null
+++ b/manual/testing.html
@@ -0,0 +1,744 @@
+
+
+
+    
+    
+    
+
+    
+    
+    
+
+    Testing Guide
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+
+    
+
+    
+    
+    
+
+
+
+
    
+	
+
+
+
    
+
    
+	
    
+		
    
+			
    
+				
    
+					
+
+        
    
+
+            
+
+
+            
+        
    
+
+        
+
+				
    
+			
    
+			
    
+				
    
+					
+
+         Improve this doc
+
+
+         Create an issue
+
+        
+
+        
    
+
+        
+
+
+
+
+				
    
+			
    
+			
    
+				    
+
+
+    
    
+        
    
+            
+
    
+
    Testing Guide
    
+
    
+
    
+
    Overview
    
+
    
+
    The AsciiDoc Linter uses Python’s unittest framework for testing. Tests are organized by rule type and functionality.
    
+
    
+
    
+
    
+
    Running Tests
    
+
    
+
    Running All Tests
    
+
    
+
    
+
    # From project root
+python run_tests.py
+
+# With coverage report
+coverage run -m unittest discover
+coverage report
    
+
    
+
    
+
    
+
    
+
    Running Specific Tests
    
+
    
+
    
+
    # Run tests for heading rules
+python -m unittest tests/rules/test_heading_rules.py
+
+# Run a specific test class
+python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule
+
+# Run a specific test method
+python -m unittest tests.rules.test_heading_rules.TestHeadingFormatRule.test_valid_format
    
+
    
+
    
+
    
+
    
+
    
+
    Test Structure
    
+
    
+
    Test Organization
    
+
    
+
    
+
    tests/
+├── __init__.py
+├── rules/
+│   ├── __init__.py
+│   ├── test_heading_rules.py
+│   └── test_block_rules.py
+├── test_cli.py
+└── test_parser.py
    
+
    
+
    
+
    
+
    
+
    Test Classes
    
+
    
+
    Each rule has its own test class:
    
+
    
+
    
+
    
+
    class TestHeadingFormatRule(unittest.TestCase):
+    def setUp(self):
+        self.rule = HeadingFormatRule()
+
+    def test_valid_format(self):
+        content = """
+        = Valid Heading
+        == Another Valid
+        """
+        findings = self.rule.check(content)
+        self.assertEqual(len(findings), 0)
    
+
    
+
    
+
    
+
    
+
    
+
    Writing Tests
    
+
    
+
    Test Guidelines
    
+
    
+
      
+
    • 
+
      Test both valid and invalid cases
      
+
      • 
+
    • 
+
      Include edge cases
      
+
      • 
+
    • 
+
      Test error messages
      
+
      • 
+
    • 
+
      Test severity levels
      
+
      • 
+
    • 
+
      Test rule configurations
      
+
      • 
+
    
+
    
+
    
+
    
+
    Example Test Pattern
    
+
    
+
      
+
    1. 
+
      Arrange: Set up test data
      
+
      2. 
+
    2. 
+
      Act: Execute the code
      
+
      3. 
+
    3. 
+
      Assert: Verify results
      
+
      4. 
+
    
+
    
+
    
+
    
+
    def test_invalid_format(self):
+    # Arrange
+    content = "=invalid heading"
+
+    # Act
+    findings = self.rule.check(content)
+
+    # Assert
+    self.assertEqual(len(findings), 2)
+    self.assertEqual(findings[0].severity, Severity.ERROR)
    
+
    
+
    
+
    
+
    
+
    
+
    Test Data
    
+
    
+
    Sample Documents
    
+
    
+
      
+
    • 
+
      Create realistic test documents
      
+
      • 
+
    • 
+
      Cover various scenarios
      
+
      • 
+
    • 
+
      Include complex cases
      
+
      • 
+
    • 
+
      Document test case purpose
      
+
      • 
+
    
+
    
+
    
+
    
+
    Test Fixtures
    
+
    
+
      
+
    • 
+
      Use setUp and tearDown
      
+
      • 
+
    • 
+
      Share common test data
      
+
      • 
+
    • 
+
      Clean up after tests
      
+
      • 
+
    
+
    
+
    
+
    
+
    
+
    Continuous Integration
    
+
    
+
    GitHub Actions
    
+
    
+
    
+
    name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run Tests
+        run: python run_tests.py
    
+
    
+
    
+
    
+
    
+
    Coverage Requirements
    
+
    
+
      
+
    • 
+
      Aim for 90%+ coverage
      
+
      • 
+
    • 
+
      Cover all code paths
      
+
      • 
+
    • 
+
      Include error conditions
      
+
      • 
+
    • 
+
      Test edge cases
      
+
      • 
+
    
+
    
+
    
+
    
+
    
+
    
+        
    
+
+        
+
+
    
+    
+    
+    
+    
+    
+    
+
    
+
+
+
+        
    
+
+        
+    
    
+
+
+			
    
+
+		
    
+	
    
+
+
+	
+    
+
+    
+
+    
+    
+
+
+    
+    
+    
+    
+    
+
+
+
+
diff --git a/manual/usage.adoc.meta b/manual/usage.adoc.meta
new file mode 100755
index 0000000..27568fe
--- /dev/null
+++ b/manual/usage.adoc.meta
@@ -0,0 +1 @@
+Usage guide
\ No newline at end of file
diff --git a/manual/usage.html b/manual/usage.html
new file mode 100644
index 0000000..0198ff5
--- /dev/null
+++ b/manual/usage.html
@@ -0,0 +1,805 @@
+
+
+
+    
+    
+    
+
+    
+    
+    
+
+    Usage Guide
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+
+    
+
+    
+    
+    
+
+
+
+
    
+	
+
+
+
    
+
    
+	
    
+		
    
+			
    
+				
    
+					
+
+        
    
+
+            
+
+
+            
+        
    
+
+        
+
+				
    
+			
    
+			
    
+				
    
+					
+
+         Improve this doc
+
+
+         Create an issue
+
+        
+
+        
    
+
+        
+
+
+
+
+				
    
+			
    
+			
    
+				    
+
+
+    
    
+        
    
+            
+
    
+
    Usage Guide
    
+
    
+
    
+
    Command Line Interface
    
+
    
+
    Basic Usage
    
+
    
+
    
+
    # Check a single file
+asciidoc-lint document.adoc
+
+# Check multiple files
+asciidoc-lint doc1.adoc doc2.adoc
+
+# Check with specific output format
+asciidoc-lint --format json document.adoc
+
+# Use specific configuration
+asciidoc-lint --config my-config.yml document.adoc
    
+
    
+
    
+
    
+
    
+
    Command Line Options
    
+
+++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    




    OptionDefaultDescription
    --format
    console
    Output format (console, json, html)
    --config
    None
    Path to configuration file
    --verbose
    False
    Enable verbose output
    --quiet
    False
    Suppress non-error output
    
+
    
+
    
+
    
+
    Configuration
    
+
    
+
    Configuration File
    
+
    
+
    
+
    # .asciidoc-lint.yml
+rules:
+  HEAD001:
+    enabled: true
+    severity: error
+  HEAD002:
+    enabled: true
+    severity: warning
    
+
    
+
    
+
    
+
    
+
    Rule Configuration
    
+
    
+
      
+
    • 
+
      Enable/disable rules
      
+
      • 
+
    • 
+
      Set severity levels
      
+
      • 
+
    • 
+
      Configure rule-specific options
      
+
      • 
+
    • 
+
      Set file patterns
      
+
      • 
+
    
+
    
+
    
+
    
+
    
+
    Output Formats
    
+
    
+
    Console Output
    
+
    
+
    
+
    document.adoc:15 ERROR: Heading level skipped
+document.adoc:23 WARNING: Heading should start with uppercase
    
+
    
+
    
+
    
+
    
+
    JSON Output
    
+
    
+
    
+
    {
+  "findings": [
+    {
+      "rule": "HEAD001",
+      "severity": "error",
+      "message": "Heading level skipped",
+      "line": 15
+    }
+  ]
+}
    
+
    
+
    
+
    
+
    
+
    HTML Report
    
+
    
+
    Generates a detailed HTML report with:
    
+
    
+
    
+
      
+
    • 
+
      Summary statistics
      
+
      • 
+
    • 
+
      Detailed findings
      
+
      • 
+
    • 
+
      Source context
      
+
      • 
+
    • 
+
      Rule explanations
      
+
      • 
+
    
+
    
+
    
+
    
+
    
+
    Integration
    
+
    
+
    Git Pre-commit Hook
    
+
    
+
    
+
    #!/bin/sh
+files=$(git diff --cached --name-only --diff-filter=ACM | grep '.adoc$')
+if [ -n "$files" ]; then
+    asciidoc-lint $files
+fi
    
+
    
+
    
+
    
+
    
+
    CI/CD Integration
    
+
    
+
    GitHub Actions Example
    
+
    
+
    name: Lint AsciiDoc
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Lint Documentation
+        run: |
+          pip install asciidoc-linter
+          asciidoc-lint docs/
    
+
    
+
    
+
    
+
    
+
    
+
    Best Practices
    
+
    
+
    Document Organization
    
+
    
+
      
+
    • 
+
      Use consistent heading levels
      
+
      • 
+
    • 
+
      Add blank lines around blocks
      
+
      • 
+
    • 
+
      Use proper formatting
      
+
      • 
+
    • 
+
      Include alt text for images
      
+
      • 
+
    
+
    
+
    
+
    
+
    Error Resolution
    
+
+
++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Table 1. Common Issues and Solutions



    IssueSolution
    Skipped heading level
    Ensure heading levels increment by one
    Missing space after =
    Add space after heading markers
    Multiple top-level headings
    Use only one level-1 heading per document
    
+
    
+
    
+
    
+
    Troubleshooting
    
+
    
+
    Common Problems
    
+
    
+
      
+
    • 
+
      Configuration file not found
      
+
      • 
+
    • 
+
      Rule conflicts
      
+
      • 
+
    • 
+
      Performance issues
      
+
      • 
+
    • 
+
      False positives
      
+
      • 
+
    
+
    
+
    
+
    
+
    Debug Mode
    
+
    
+
    
+
    # Enable debug output
+asciidoc-lint --debug document.adoc
+
+# Show rule processing details
+asciidoc-lint --verbose document.adoc
    
+
    
+
    
+
    
+
    
+
    
+
    
+        
    
+
+        
+
+
    
+    
+    
+    
+    
+    
+    
+
    
+
+
+
+        
    
+
+        
+    
    
+
+
+			
    
+
+		
    
+	
    
+
+
+	
+    
+
+    
+
+    
+    
+
+
+    
+    
+    
+    
+    
+
+
+
+
diff --git a/search.html b/search.html
index 5fe2312..7e67e6e 100644
--- a/search.html
+++ b/search.html
@@ -216,6 +216,10 @@
                 arc42
             
 
+            
  • 
+                manual
+            
    • 
+
         
     
    
     
    
diff --git a/sitemap.xml b/sitemap.xml
index 58866cb..104326c 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -27,12 +27,12 @@
     
 
     
-    	http://jbake.org/arc42/10_quality_requirements.html
+    	http://jbake.org/arc42/index.html
     	2024-11-26
     
 
     
-    	http://jbake.org/arc42/index.html
+    	http://jbake.org/arc42/10_quality_requirements.html
     	2024-11-26
     
 
@@ -56,13 +56,43 @@
     	2024-11-26
     
 
+    
+    	http://jbake.org/arc42/02_architecture_constraints.html
+    	2024-11-26
+    
+
     
     	http://jbake.org/arc42/06_runtime_view.html
     	2024-11-26
     
 
     
-    	http://jbake.org/arc42/02_architecture_constraints.html
+    	http://jbake.org/manual/testing.html
+    	2024-11-26
+    
+
+    
+    	http://jbake.org/manual/development.html
+    	2024-11-26
+    
+
+    
+    	http://jbake.org/manual/usage.html
+    	2024-11-26
+    
+
+    
+    	http://jbake.org/manual/introduction.html
+    	2024-11-26
+    
+
+    
+    	http://jbake.org/manual/index.html
+    	2024-11-26
+    
+
+    
+    	http://jbake.org/manual/rules.html
     	2024-11-26