Documentation and review tools¶
The repository's Markdown guides build with MkDocs. Root README and contribution instructions are included directly, so they do not acquire separate stale copies. Repository source links point to the build's Git revision on GitHub. Runtime installation does not require the documentation toolchain.
Build and preview¶
Use the development virtual environment and installed frontend dependencies:
python -m pip install -r requirements-docs.txt
python scripts/generate_dashboard_fixture.py --check
python -m mkdocs build --strict
npm --prefix src/archon_horizon/frontend run build:demo
python scripts/assemble_docs_demo.py
npm --prefix src/archon_horizon/frontend run test:demo
npm --prefix src/archon_horizon/frontend run test:docs
python -m http.server 8000 --bind 127.0.0.1 --directory _site
Open http://127.0.0.1:8000/ or /demo/. The frontend demo uses relative asset
URLs and keeps navigation on its current path, including GitHub Pages' repository
subpath. The browser check serves the artifact below /Archon-Horizon/demo/ and
checks navigation, reload, graph rendering, read-only behavior, and absence of
API/external network requests. build:demo leaves the normal packaged dashboard
in frontend/dist/ untouched.
The documentation browser check verifies navigation, persisted light/dark mode,
and browser errors under the same repository subpath. It substitutes the optional
highlight.js CDN assets so theme checks do not depend on third-party availability.
The MkDocs theme's color toggle requires its highlight.js stylesheet elements;
keep highlightjs enabled with the light/dark toggle.
After editing the synthetic example, run
python scripts/generate_dashboard_fixture.py, then repeat the build and browser
check. The generated JSON is versioned and the generator's --check detects drift.
GitHub Pages¶
The Documentation workflow builds and uploads an artifact for pull requests and
pushes to main. To publish a reviewed build, select GitHub Actions as the
repository's Pages source, then run Documentation on main with publish
enabled. The deploy job uses the github-pages environment and the minimum Pages
permissions. Ordinary PR/push builds do not deploy. The expected URL is
https://frenzymath.github.io/Archon-Horizon/; a different repository name requires
updating site_url in mkdocs.yml.
Review inventory¶
scripts/review_inventory.py reads Python syntax without importing application
code or contacting an installation:
python scripts/review_inventory.py --format markdown --output "$TMPDIR/review-inventory.md"
python scripts/review_inventory.py --output "$TMPDIR/review-inventory.json"
python scripts/review_inventory.py --coverage coverage.json --review-ledger review.json
It lists every Python file and function in the selected source tree, including
nested functions and methods, with lines, docstrings, comments, branch counts and
nesting. Pass --source scripts to review development tools. The default source
is src/archon_horizon; generated dependency/build directories are excluded.
Optional --coverage accepts coverage.py JSON line data. Coverage is reported as
observed executable lines, not branch coverage or proof of correctness. Optional
--review-ledger accepts explicit reviewed function names:
{
"scripts/review_inventory.py": {
"reviewed_functions": ["scan", "main"],
"notes": "Read source and checked malformed-input behavior."
}
}
Missing evidence stays unknown. Function names include their class/parent scope and line number distinguishes same-name definitions. Metrics identify useful review targets; they do not determine whether a function should exist or whether its behavior is correct. Record concrete findings and validation in the review notes, including any unreviewed scope.