Building Documentation and Test Reports¶

This guide provides detailed instructions for building static documentation sites and test coverage reports for GitTinkerer.

Overview¶

GitTinkerer provides two types of build outputs:

Documentation Site - Unified documentation from all markdown files, built with MkDocs
Test Coverage Report - HTML coverage report from Vitest test runs

Both outputs are fully static and can be served via any web server (nginx, Apache, etc.).

Prerequisites¶

For Documentation Building¶

Python 3.11+ - Required for MkDocs and plugins
pip - Python package installer

For Test Report Building¶

Node.js 24.x - Service runtime requirement
npm - Node package manager

Installation¶

Installing Documentation Dependencies¶

Install Python dependencies for MkDocs:

# Using Makefile
make install-docs-deps

# Or manually
pip install -r requirements.txt

This installs: - mkdocs - Core documentation generator - mkdocs-material - Material Design theme - pymdown-extensions - Markdown extensions - mkdocs-mermaid2-plugin - Mermaid diagram support

Installing Service Dependencies¶

If not already done, install Node.js dependencies:

cd service
npm install

Building Documentation¶

Quick Build¶

# Using Makefile (recommended)
make build-docs

# Or manually
mkdocs build

Output Location: site/index.html

Local Preview¶

To preview documentation locally with live reload:

mkdocs serve

This starts a development server at http://127.0.0.1:8000 with automatic reloading when markdown files are edited.

Build Options¶

MkDocs supports additional build options:

# Clean build (remove site/ first)
mkdocs build --clean

# Verbose output
mkdocs build --verbose

# Custom config file
mkdocs build --config-file custom-mkdocs.yml

Building Test Reports¶

Quick Build¶

# Using Makefile (recommended)
make build-test-report

# Or manually
cd service && npm run test:coverage

Output Location: service/coverage/index.html

Understanding Test Coverage¶

The test report includes: - Line Coverage - Percentage of code lines executed during tests - Branch Coverage - Percentage of code branches (if/else) covered - Function Coverage - Percentage of functions called - Statement Coverage - Percentage of statements executed

Coverage thresholds are enforced: - Line: 80% - Function: 75% - Statement: 80% - Branch: 70%

Running Specific Test Suites¶

cd service

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# Full test run without coverage
npm run test:run

# Interactive UI
npm run test:ui

Building Both Outputs¶

To build both documentation and test reports in one command:

make build-all

This runs: 1. make build-docs - Builds documentation to site/ 2. make build-test-report - Builds test report to service/coverage/

Cleaning Build Outputs¶

Remove all generated files:

make clean

This deletes: - site/ - Documentation output - service/coverage/ - Test coverage output

CI/CD Integration¶

GitHub Actions Workflow¶

The CI workflow (.github/workflows/ci.yml) automatically builds both artifacts:

Documentation Build Job¶

build-docs:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: '3.11'
    - run: pip install -r requirements.txt
    - run: mkdocs build
    - uses: actions/upload-artifact@v4
      with:
        name: mkdocs-site
        path: site

Test Report from Test Job¶

The existing test job uploads coverage after running tests:

- name: Upload coverage artifacts
  uses: actions/upload-artifact@v4
  with:
    name: test-report
    path: service/coverage

Accessing CI Artifacts¶

After a CI run completes:

Go to the workflow run page in GitHub Actions
Scroll to "Artifacts" section
Download:
mkdocs-site - Documentation site
test-report - Test coverage report
Extract and open index.html in a browser

Documentation Structure¶

The built documentation includes:

Home - Project overview (from README.md)
Architecture - System design and diagrams
Development - Setup and development guide
API Reference - Complete API documentation
Operations - Operational procedures
Observability - Monitoring and debugging
GitHub App Setup - Webhook configuration
Bash Modules - Runner module reference
Building - This guide
Service - Service-specific documentation
Web - Web UI documentation

Troubleshooting¶

MkDocs Build Failures¶

Error: mkdocs: command not found

Solution: Install Python dependencies

pip install -r requirements.txt

Error: Config file 'mkdocs.yml' not found

Solution: Run from repository root

cd /path/to/GitTinkerer
mkdocs build

Test Coverage Build Failures¶

Error: npm: command not found

Solution: Install Node.js 24.x

# Using nvm
nvm install 24
nvm use 24

Error: Coverage thresholds not met

Solution: Add more tests or adjust thresholds in vitest.config.ts

Error: Database connection failed

Solution: Integration tests require a test database. Set DATABASE_URL_TEST environment variable.

Permission Errors¶

Error: Permission denied when writing to site/ or service/coverage/

Solution: Ensure write permissions for build directories

chmod -R u+w site/ service/coverage/

Serving Built Documentation¶

Using Python HTTP Server¶

cd site
python3 -m http.server 8000
# Access at http://localhost:8000

Using MkDocs Serve (Development Only)¶

mkdocs serve --dev-addr=0.0.0.0:8000

Note: This rebuilds on file changes. Use mkdocs build for production.

Using nginx¶

Example nginx configuration:

server {
    listen 80;
    server_name docs.example.com;

    root /path/to/GitTinkerer/site;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Advanced Configuration¶

Custom MkDocs Themes¶

To use a different theme, edit mkdocs.yml:

theme:
  name: readthedocs  # or another theme

Additional Markdown Extensions¶

Add extensions to mkdocs.yml:

markdown_extensions:
  - footnotes
  - tables
  - abbr

Custom Test Coverage Reporters¶

Edit vitest.config.ts to add reporters:

export default defineConfig({
  test: {
    coverage: {
      reporter: ['html', 'lcov', 'text', 'json']
    }
  }
});

Build Output Locations Summary¶

Output	Location	Entry Point
Documentation	`site/`	`site/index.html`
Test Coverage	`service/coverage/`	`service/coverage/index.html`

Both directories contain fully static HTML/CSS/JS and can be deployed to any static hosting service.

Development Guide - Local setup and testing
Architecture - System design
CI/CD Workflow - Automated builds

Building Documentation and Test Reports¶

Overview¶

Prerequisites¶

For Documentation Building¶

For Test Report Building¶

Installation¶

Installing Documentation Dependencies¶

Installing Service Dependencies¶

Building Documentation¶

Quick Build¶

Local Preview¶

Build Options¶

Building Test Reports¶

Quick Build¶

Understanding Test Coverage¶

Running Specific Test Suites¶

Building Both Outputs¶

Cleaning Build Outputs¶

CI/CD Integration¶

GitHub Actions Workflow¶

Documentation Build Job¶

Test Report from Test Job¶

Accessing CI Artifacts¶

Documentation Structure¶

Troubleshooting¶

MkDocs Build Failures¶

Test Coverage Build Failures¶

Permission Errors¶

Serving Built Documentation¶

Using Python HTTP Server¶

Using MkDocs Serve (Development Only)¶

Using nginx¶

Advanced Configuration¶

Custom MkDocs Themes¶

Additional Markdown Extensions¶

Custom Test Coverage Reporters¶

Build Output Locations Summary¶

Related Documentation¶