Skip to content

Docs Workflow

This site is MkDocs Material, with the API Reference generated by mkdoxy/Doxygen. Here's how to make a docs change and ship it.

Local setup

pip install mkdocs-material mkdoxy

Doxygen must also be on your system (Homebrew or the official package on macOS) — mkdoxy calls it during the build.

Build check — always strict

Run a strict build before opening a PR. It catches broken links, bad nav paths, and missing anchors:

mkdocs build -f docs/mkdocs.yml --strict

This writes the local site/ directory — build output only, gitignored, never committed.

Local preview

mkdocs serve -f docs/mkdocs.yml -a 127.0.0.1:8010
# → http://127.0.0.1:8010/OpenSkyhawk/

The /OpenSkyhawk/ prefix matches the GitHub Pages path, so it catches broken absolute links before they ship.

Writing pages

  • New pages start from the stub template (status: stub + a WIP admonition). Use the status badges honestly.
  • Don't touch docs/api/ — it's auto-generated by mkdoxy. Only docs/api/index.md and docs/api/deprecated.md are committed; everything else is regenerated each build.
  • Don't collapse the API Reference nav in mkdocs.yml — leave its nested structure intact.
  • docs/_source/ holds the old AI working notes — source material to extract facts from, not published. Rewrite, don't transcribe.

Publishing — automatic

You don't deploy manually. A GitHub Actions workflow (docs-deploy.yml) builds the site and pushes it to the gh-pages branch on every push to main. Merge your PR and the live site updates in a couple of minutes.

Don't run mkdocs gh-deploy by hand

Publishing is owned by the workflow. Running gh-deploy from a feature branch would push unmerged content to the live site. Let the merge trigger the deploy.

Assets

Reference only committed, optimised assets. Work-in-progress mock images live under docs/assets/source-mocks/ — gitignored and excluded from the build.