Serve documentation from the operator UI

2026-08-02 15:50:07 +03:00
parent 284aef5d6f
commit f20cc7fe00
72 changed files with 3509 additions and 698 deletions
@@ -0,0 +1,93 @@
+# 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:
+
+```markdown
+!!! 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
+
+```bash
+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.