Documentation Guide¶

The documentation site is built with MkDocs and a custom Doriax theme. Source pages live under docs/; generated site output lives under site/.

Local preview¶

pip install -r requirements.txt
mkdocs serve
mkdocs build --strict

Reference documentation¶

API reference pages live under docs/reference/classes/. Each file documents one class with C++ and Lua on the same page (Supernova-style).

Do not use a bulk markdown generator in this repo. Pages are edited by hand.

Inventory tool¶

To list every bound class, method, and property, run the engine script (reference only):

python3 /path/to/doriax/generate_api_suggestions.py \
  engine/core/script/binding /tmp/out.h engine/core

Use that output when adding or verifying APIs. Then edit the matching docs/reference/classes/<name>.md file and add descriptions for important methods.

Priority for descriptions¶

Expand these first when touching the reference: Engine, Scene, Object, Input, Camera, Body2D, Body3D, PhysicsSystem, Mesh, Sprite, Action, Animation.

Page structure¶

1. Short class description
2. Properties / Methods / Events tables with a Languages column (C++ | Lua)
3. Method details for important APIs (tabbed C++ / Lua examples)
4. Enumerations when relevant

File organization¶

Links¶

Use relative links. Run mkdocs build --strict after nav or path changes.

Versioned documentation¶

The published site carries one build per release series plus the in-development docs from main:

main is always the unstable docs. Changes land there and reach the stable URLs only when a release is tagged, so a page describing an unreleased feature does not have to be held back.

Each series is built from its highest patch tag (v0.7.0, v0.7.1 → 0.7, built from v0.7.1). Pre-release tags are ignored.

scripts/build-versions.sh assembles the whole tree: it builds every series, mirrors the newest one at the root, and writes versions.json, which drives the version picker in the header. Old builds read that file at runtime, so they list newer releases without being rebuilt.

mkdocs serve builds only the unstable version, and the picker stays hidden because there is no versions.json to read. To preview the full versioned site:

scripts/build-versions.sh site
python3 -m http.server -d site

Releasing a version¶

Tag the documentation repository when the matching engine release goes out:

git tag v0.7.1
git push origin v0.7.1

The tag push rebuilds and redeploys every version. Only the tagged commit's own docs/ is published for that version, so the tag must point at the commit whose docs describe the release.

Correcting published docs means moving the tag, since a tag is the only thing the build reads:

git commit -am "Fix physics layer description"   # on main
git tag -f v0.7.1 && git push -f origin v0.7.1

The github-pages environment must allow tags to deploy, or the tag run builds the site and then fails at the deploy step: under Settings → Environments → github-pages → Deployment branches and tags, v* needs a tag rule alongside the main branch rule.

Layout and theme changes¶

Only docs/ and mkdocs.yml come from a release tag. Every version is built with the theme from main, so a fix to the header, CSS, or search reaches all published versions on the next build, and a version tagged before a theme feature existed still gets it.

The trade-off is that a theme change has to keep rendering older content. Preview one against the real thing before pushing:

scripts/build-versions.sh site        # every version, current theme
DOCS_SHARED_THEME=0 scripts/build-versions.sh site   # each version's own theme

versions.json is a compatibility contract in the other direction: already published builds parse it with the JavaScript they shipped with. Add fields to it, never rename or remove them.