Maintain the documentation¶
The product site is built from repository Markdown with MkDocs Material and published by GitHub Actions to https://inferplane.github.io/inferplane/. The site describes the current main branch; it is not a versioned API compatibility promise.
Preview and validate¶
python3 -m venv .venv-docs
.venv-docs/bin/python -m pip install -r requirements-docs.txt
.venv-docs/bin/python -m mkdocs serve
Open the loopback URL printed by MkDocs. To run the same documentation checks as CI:
.venv-docs/bin/python -m unittest discover -s tests/docs -v
.venv-docs/bin/python scripts/check_docs_translations.py
.venv-docs/bin/python -m mkdocs build --strict
.venv-docs/bin/python scripts/check_docs_site.py site
Dependencies are pinned in requirements-docs.txt. To update intentionally, change requirements-docs.in, resolve a new lock with uv pip compile --generate-hashes, and review the dependency diff.
Editorial contract¶
Write for the operator's task: prerequisites, supported configuration, expected result, failure behavior, and next step. Keep alpha status and profile-specific limits visible. Distinguish implementation, automated testing, live-model compatibility and production qualification.
New behavior must link to its reference and decision. New operational procedures must preserve credentials, identity history, audit evidence and outstanding authority. Never turn examples into claims about current model availability or pricing.
mkdocs.yml owns navigation. Historical specifications/plans and customer analysis remain in GitHub; they are excluded from site navigation and search. ADRs remain searchable with their original status. The hook rewrites links to repository-only files/directories into GitHub source links. After adding or renaming an ADR, run python scripts/docs_hooks.py to regenerate the committed English/Korean ADR indexes; validation rejects a stale index.
Performance measurements¶
The performance pages use the reviewed, sanitized snapshot
in docs/assets/data/performance.json. Run python scripts/build_performance_docs.py
to regenerate tables, then --check to verify their committed output. CI does not
need private recordings or model access. The explicit --import-recordings option
refreshes the public snapshot from local recordings after review; raw prompts,
responses, error bodies and credentials must remain outside the published data.
Review both languages when updating a snapshot. Development-build measurements
must be labeled separately from functionality available in main.
Korean and English¶
English stays at the existing root URL; Korean is under /ko/. The language
selector follows the current page. Add a sibling page.ko.md for every published
product, operations, API, implementation-reference and project document. ADRs
remain English originals with a Korean index and an explicit original-language
notice. Historical plans/specifications stay outside the published site.
Preserve commands, field names, code examples and safety conditions. Give translated
headings the original English anchor with {#original-anchor} so existing deep links
work in either language. Update the original and translation together; retain the
translation_source path and set translation_source_sha256 to the SHA-256 of the
reviewed English file after translating its changes. The check detects missing and
outdated translations; a matching hash alone does not prove translation quality.
Review the meaning as well as updating the marker. Keep both languages' search,
metadata, navigation, and mobile language switch under browser verification.
Publication¶
The documentation workflow validates every PR. Only a successful build from a push to main, or a manual run on main, can deploy. The deployment job alone has Pages-write/OIDC permissions and uses the github-pages environment. Concurrent publications are serialized.
Repository administrators must configure Pages to use GitHub Actions. The first deployment creates the published site. Review a preview/build before merging; publication follows the repository's required AI review and CI gates.
For future changes, check the deployed URL, navigation, search, mobile layout and deep links after the workflow succeeds. Never bypass review checks to publish documentation.