Documentation Pipeline Developer Guide

Prerequisites

  • Python 3.10+
  • Install dependencies: pip install -r requirements.txt
  • Optional: create a virtual environment for isolation.

Workflow

  1. Generate or update the knowledge-base index: bash make kb
  2. Parse a Loxone configuration export (default 110 Bullhead Road.loxone) and produce _data/v2/config.json: bash make parse
  3. Render Markdown documentation into docs/manual/<export_hash>/: bash make generate
  4. Validate the generated manuals for broken links and unresolved KB references: bash make validate
  5. Run formatting and tests: bash make lint make test

Use make docs to execute steps 1–4 or make all to run the entire pipeline including linting and tests.

Data Schema

  • Parsed configuration snapshots are written to _data/v2/config.json with provenance in _data/v2/provenance.json.
  • The JSON schema captures rooms, categories, blocks (including connector metadata), devices, virtual inputs/outputs, schedules, and lighting subsystem detail.
  • tools/docs/kb_lookup.json stores block_type -> {title, url, summary} mappings derived from the Markdown knowledge base. Manual overrides live in tools/docs/kb_overrides.yml.

Troubleshooting

  • Missing KB links: Add or adjust entries in tools/docs/kb_overrides.yml and rerun make kb.
  • Validation failures: Run python tools/validate_docs.py --docs docs/manual --kb-lookup tools/docs/kb_lookup.json to view detailed errors.
  • Template updates: Modify files in tools/templates/ and rerun make generate.

Testing

  • Automated tests live under tests/ and cover parsing, KB indexing, rendering, and validation.
  • Execute pytest or make test before committing changes.