/ Current View source
Projects/ImmuKnow Studio/Documentation and releases

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.