Documentation approach

These rules are the contract for this site. Every page must follow them; reviewers enforce them.

1. Purpose and scope

This MkDocs site documents the Workload SDK: how to use it, how to author workloads, and the complete scimesh.sdk API. It does not host the project's internal documentation (contracts, task briefs, planning documents) — those live in the repository's docs/ directory and are not part of the site. Where a guide needs a contract detail, link to the repository file in prose; do not copy its content.

2. Page types and status markers

Every page starts with one of:

concept — explains a model (for example the SDK overview);
guide — how to accomplish a task (authoring workloads, CLI, worker);
reference — generated API documentation, never hand-written.

Guides may be marked with an admonition when a section describes future or fail-closed behavior:

!!! warning "Not yet supported"
    The v1 coordinator contract does not persist resource requirements...

3. The reference is generated, not written

api/ pages contain only mkdocstrings directives (::: scimesh.sdk.<module>); editing them by hand is an error.
Public API must be documented in Google-style docstrings in the code: Args:, Returns:, Raises:.
Every validation failure and fail-closed path must be documented in the docstring.
After any docstring change, rebuild: make docs.

4. Terminology

Use the single glossary from PLAN.md:

Term	Meaning
Job / Run	A user-requested full computation
Task	One independently executable unit of a job
Attempt	A lease for one task execution
Artifact	A durable input, shard, partial, or final result
Workload	A user script (package) built on the SDK

Never introduce synonyms (pipeline, run for task, etc.). The word "workload" in this site means an SDK workload (a user script), not a "workload" in the performance sense.

5. Code and output conventions

Use language-tagged fenced blocks: python, bash, text, json.
Never include local machine paths, tokens, or private data in examples.
Show complete runnable examples; prefer the real built-in workloads (molwt-filter, descriptor-batch) over invented ones.
Keep command output minimal and accurate; regenerate it, don't retype it.

6. Linking

Relative links inside mkdocs/ (for example ../api/sdk-batch.md).
Repository files outside the site (docs/, PLAN.md) are referenced in prose with their path, not linked as site pages.
Every guide must link to the relevant API pages.

7. When to write or update

New workload → update sdk/authoring-workloads.md examples and the UI workload catalog (make workloads-export).
SDK API change → update docstrings; the reference rebuilds.
Worker/coordinator behavior change → update sdk/worker-integration.md and the fail-closed warnings.
New CLI surface → update sdk/cli.md.
Behavior changes without documentation updates are incomplete changes.

8. Build and verification

make docs          # build into site/
make docs-serve    # http://localhost:8000

mkdocs build must succeed with no errors.
New or changed pages must render (check the generated HTML, not just the markdown).
The site is served inside the coordinator UI at /ui/docs/; the demo mounts site/ automatically.

3.4 KiB Raw Blame History