From 4d3ab720cc078a410ff81e241540f49578b27706 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ralf=20D=2E=20M=C3=BCller?= Date: Tue, 26 Nov 2024 18:13:11 +0100 Subject: [PATCH] added manual --- docToolchainConfig.groovy | 0 docs/manual/.meta | 1 + docs/manual/development.adoc | 109 +++++++++++++++++ docs/manual/development.adoc.meta | 1 + docs/manual/index.adoc | 16 +++ docs/manual/index.adoc.meta | 1 + docs/manual/introduction.adoc | 64 ++++++++++ docs/manual/introduction.adoc.meta | 1 + docs/manual/rules.adoc | 188 +++++++++++++++++++++++++++++ docs/manual/rules.adoc.meta | 1 + docs/manual/testing.adoc | 138 +++++++++++++++++++++ docs/manual/testing.adoc.meta | 1 + docs/manual/usage.adoc | 179 +++++++++++++++++++++++++++ docs/manual/usage.adoc.meta | 1 + 14 files changed, 701 insertions(+) mode change 100644 => 100755 docToolchainConfig.groovy create mode 100755 docs/manual/.meta create mode 100755 docs/manual/development.adoc create mode 100755 docs/manual/development.adoc.meta create mode 100755 docs/manual/index.adoc create mode 100755 docs/manual/index.adoc.meta create mode 100755 docs/manual/introduction.adoc create mode 100755 docs/manual/introduction.adoc.meta create mode 100755 docs/manual/rules.adoc create mode 100755 docs/manual/rules.adoc.meta create mode 100755 docs/manual/testing.adoc create mode 100755 docs/manual/testing.adoc.meta create mode 100755 docs/manual/usage.adoc create mode 100755 docs/manual/usage.adoc.meta diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy old mode 100644 new mode 100755 diff --git a/docs/manual/.meta b/docs/manual/.meta new file mode 100755 index 0000000..7800c8e --- /dev/null +++ b/docs/manual/.meta @@ -0,0 +1 @@ +Manual folder for detailed documentation \ No newline at end of file diff --git a/docs/manual/development.adoc b/docs/manual/development.adoc new file mode 100755 index 0000000..9be8e09 --- /dev/null +++ b/docs/manual/development.adoc @@ -0,0 +1,109 @@ +// development.adoc - Development guide += Development Guide + +== Setting Up Development Environment + +=== Clone the Repository + +[source,bash] +---- +git clone https://github.com/yourusername/asciidoc-linter.git +cd asciidoc-linter +---- + +=== Create Virtual Environment + +[source,bash] +---- +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate +pip install -e . +---- + +== Project Structure + +[source] +---- +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: ++ +[source,python] +---- +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. Add tests for the rule +3. Register the rule in the linter +4. 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 + +1. Create feature branch +2. Implement changes +3. Add/update tests +4. Update documentation +5. Submit PR + +== Release Process + +1. Update version number +2. Update changelog +3. Run full test suite +4. Create release notes +5. Tag release +6. Build and publish \ No newline at end of file diff --git a/docs/manual/development.adoc.meta b/docs/manual/development.adoc.meta new file mode 100755 index 0000000..df869c1 --- /dev/null +++ b/docs/manual/development.adoc.meta @@ -0,0 +1 @@ +Development guide \ No newline at end of file diff --git a/docs/manual/index.adoc b/docs/manual/index.adoc new file mode 100755 index 0000000..f371dd6 --- /dev/null +++ b/docs/manual/index.adoc @@ -0,0 +1,16 @@ +// index.adoc - Main documentation += AsciiDoc Linter Manual +:toc: left +:icons: font +:source-highlighter: rouge +:experimental: + +include::introduction.adoc[leveloffset=+1] + +include::development.adoc[leveloffset=+1] + +include::testing.adoc[leveloffset=+1] + +include::usage.adoc[leveloffset=+1] + +include::rules.adoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/manual/index.adoc.meta b/docs/manual/index.adoc.meta new file mode 100755 index 0000000..22930bd --- /dev/null +++ b/docs/manual/index.adoc.meta @@ -0,0 +1 @@ +Main documentation file that includes all other parts \ No newline at end of file diff --git a/docs/manual/introduction.adoc b/docs/manual/introduction.adoc new file mode 100755 index 0000000..5c5f1d7 --- /dev/null +++ b/docs/manual/introduction.adoc @@ -0,0 +1,64 @@ +// introduction.adoc - Project introduction += 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 + +.Technology Stack +[cols="1,4"] +|=== +|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 + +[source,bash] +---- +# Install the package +pip install asciidoc-linter + +# Run a basic check +asciidoc-lint your-document.adoc + +# Get help +asciidoc-lint --help +---- \ No newline at end of file diff --git a/docs/manual/introduction.adoc.meta b/docs/manual/introduction.adoc.meta new file mode 100755 index 0000000..8e38592 --- /dev/null +++ b/docs/manual/introduction.adoc.meta @@ -0,0 +1 @@ +Introduction to the project \ No newline at end of file diff --git a/docs/manual/rules.adoc b/docs/manual/rules.adoc new file mode 100755 index 0000000..172d4ba --- /dev/null +++ b/docs/manual/rules.adoc @@ -0,0 +1,188 @@ +// rules.adoc - Rule documentation += Rule Reference + +== Heading Rules + +=== HEAD001: Heading Incrementation + +Ensures that heading levels are properly incremented and no levels are skipped. + +.Valid Example +[source,asciidoc] +---- += Level 1 +== Level 2 +=== Level 3 +---- + +.Invalid Example +[source,asciidoc] +---- += Level 1 +=== Level 3 # Error: Skipped level 2 +---- + +.Configuration Options +[cols="1,1,2"] +|=== +|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 +[source,asciidoc] +---- += Title +== Section +=== Subsection +---- + +.Invalid Examples +[source,asciidoc] +---- +=Title # Error: Missing space += title # Warning: Lowercase +==Section # Error: Missing space +---- + +.Configuration Options +[cols="1,1,2"] +|=== +|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 +[source,asciidoc] +---- += Document Title +== Section 1 +== Section 2 +---- + +.Invalid Example +[source,asciidoc] +---- += First Title +== Section 1 += Second Title # Error: Multiple top-level headings +---- + +.Configuration Options +[cols="1,1,2"] +|=== +|Option |Default |Description + +|enabled +|true +|Enable/disable rule + +|severity +|error +|Rule severity level +|=== + +== Planned Rules + +=== BLOCK001: Block Termination + +[.planned] +Checks for properly terminated blocks. + +.Valid Example +[source,asciidoc] +---- +[source,python] +---- +def hello(): + print("Hello") +---- +---- + +.Invalid Example +[source,asciidoc] +---- +[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. + +[source] +---- +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*) \ No newline at end of file diff --git a/docs/manual/rules.adoc.meta b/docs/manual/rules.adoc.meta new file mode 100755 index 0000000..d158f06 --- /dev/null +++ b/docs/manual/rules.adoc.meta @@ -0,0 +1 @@ +Documentation of all rules \ No newline at end of file diff --git a/docs/manual/testing.adoc b/docs/manual/testing.adoc new file mode 100755 index 0000000..ccdaf22 --- /dev/null +++ b/docs/manual/testing.adoc @@ -0,0 +1,138 @@ +// testing.adoc - Testing guide += 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 + +[source,bash] +---- +# From project root +python run_tests.py + +# With coverage report +coverage run -m unittest discover +coverage report +---- + +=== Running Specific Tests + +[source,bash] +---- +# 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 + +[source] +---- +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: + +[source,python] +---- +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. Act: Execute the code +3. Assert: Verify results + +[source,python] +---- +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 + +[source,yaml] +---- +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 \ No newline at end of file diff --git a/docs/manual/testing.adoc.meta b/docs/manual/testing.adoc.meta new file mode 100755 index 0000000..b7f4630 --- /dev/null +++ b/docs/manual/testing.adoc.meta @@ -0,0 +1 @@ +Testing guide \ No newline at end of file diff --git a/docs/manual/usage.adoc b/docs/manual/usage.adoc new file mode 100755 index 0000000..752b949 --- /dev/null +++ b/docs/manual/usage.adoc @@ -0,0 +1,179 @@ +// usage.adoc - Usage guide += Usage Guide + +== Command Line Interface + +=== Basic Usage + +[source,bash] +---- +# 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 + +[cols="1,1,2"] +|=== +|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 + +[source,yaml] +---- +# .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 + +[source] +---- +document.adoc:15 ERROR: Heading level skipped +document.adoc:23 WARNING: Heading should start with uppercase +---- + +=== JSON Output + +[source,json] +---- +{ + "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 + +[source,bash] +---- +#!/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 +[source,yaml] +---- +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 + +.Common Issues and Solutions +[cols="1,2"] +|=== +|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 + +[source,bash] +---- +# Enable debug output +asciidoc-lint --debug document.adoc + +# Show rule processing details +asciidoc-lint --verbose document.adoc +---- \ No newline at end of file diff --git a/docs/manual/usage.adoc.meta b/docs/manual/usage.adoc.meta new file mode 100755 index 0000000..27568fe --- /dev/null +++ b/docs/manual/usage.adoc.meta @@ -0,0 +1 @@ +Usage guide \ No newline at end of file