94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 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.
|