Documentation and releases¶
Where documentation belongs¶
Studio owns its manual in this repository's docs/, its navigation in
mkdocs.yml, and its locked documentation dependencies in pyproject.toml and
uv.lock. Change these alongside the behavior they explain.
The WDGPH/docs repository owns the shared PHIZ presentation, project catalogue, release registry, search and one documentation deployment at docs.phiz.ca. It builds each manual from the source repository at the selected commit. Do not copy Studio's Markdown or generated HTML into that repository.
Studio's application continues to be built and hosted by its Studio Pages workflow. Documentation builds do not build the browser compiler, run the application build or deploy the application.
Write for readers¶
Explain the action and its result in plain language. Use the exact labels shown in Studio and keep step-by-step user guidance separate from build instructions. Explain technical terms where readers first need them. Describe current behavior directly, without recounting development history. Use fictional records and public assets in examples. Follow the shared language and project responsibilities.
Keep the relationship to ImmuKnow explicit: Studio develops templates; local ImmuKnow runs generate production notices. Link to ImmuKnow's manual for input validation, the facts contract and delivery review instead of duplicating it. Keep ImmuKnow’s configured Git reference and exact locked commit distinct from its release tags.
Check a documentation change¶
uv sync --locked --no-default-groups --group docs
uv run --locked --no-default-groups --group docs mkdocs build --strict
uv run --locked --no-default-groups --group docs mkdocs serve
Open the local address printed by MkDocs. Check navigation, links, commands and rendered tables. The Studio documentation workflow runs the strict build on pull requests and main pushes and retains the output for review. The local Material preview checks source rendering; the hub supplies the public theme and search.
For a shared-theme preview after Studio is registered, follow the
hub's local source preview instructions.
Supply --source immuknow-studio=/path/to/ImmuKnow-Studio to its preview build.
Stage new source files first so the snapshot includes them. Preview output stays
local and is never a publication artifact.
Publish the manual¶
The hub's projects.json registers source repositories and versions.lock.json
records release state. Follow the hub source-project instructions
when registering or updating a manual. Run its full build and browser checks
before publication. The development manual uses /immuknow-studio/latest/.
For a tagged release, review the hub's release refresh and build the resulting
lock change against the actual tagged commit before merging.
The optional docs-hub-notify.yml workflow follows the hub's notification
contract. Configure DOCS_HUB_TRIGGER_TOKEN and DOCS_HUB_NOTIFY_ENABLED
according to the hub's credential instructions.
It requests a hub rebuild for main changes and a reviewed release refresh for
tag changes; it sends no generated HTML.
For a Studio release, review the journey from editing through the downloaded project and native run. Run the checks in Build and contribute and the strict documentation build. Verify the ImmuKnow pin and compiler identity, keep package versions and the release tag consistent, and record the checks.