Docstring & documentation conventions

altar is an independent, publishable package. Its docstrings and docs ship inside the wheel and render on the docs site, so they must stand on their own — a reader who has only pip installed the package, with no access to any host application or internal design docs, must be able to understand every comment. This page is the convention that keeps that true.

The rule of thumb: explain the engineering, not the provenance. Preserve every genuine rationale (why a seam exists, path algebra, Kleene semantics, why a call offloads to a thread). Remove anything that only makes sense inside a particular private repository.

This page covers what a docstring may reference. For how to write the prose itself — the plain, human style every docstring here must follow — see Writing style. Read that first.

Do not reference

1. Internal/private design documents. No SOME_DESIGN.md §4-style citations. Those documents do not ship with the package, so the reference dangles. Inline the decision itself if it's worth keeping; otherwise drop the citation and keep the prose.

2. Absolute line numbers into other files. foo.py:1243, :698-700, and similar drift the moment either file changes and are meaningless to an outside reader. Describe the behavior instead (a code snippet in backticks is fine; the private line citation is not).

3. A specific host application or its modules. Don't name a private application package, its submodules, its infra adapters, or private class names as if the reader can see them. Refer to integrators generically: "the private host application", "a hosted deployment", "a private infra adapter".

4. A specific named production cluster or environment. Describe capabilities generically — "a production K8s cluster", "the reference production deployment", "a self-managed K8s cluster" — not by a proper noun that only means something internally.

5. In-flight migration framing. No "Phase 2", "step 4", "the strangler phase", "once it's extracted", "not yet packaged". State the design as present-tense fact. A sentence whose only content is migration sequencing should be deleted.

6. Back-compat justified by a private caller. If a symbol is kept as a stable alias, say "kept as a stable public alias" — don't justify it by a private call site or an internal test.

The import boundary (keep this — just de-name it)

altar must not import from any private host application. That rule is real and machine-enforced; keep stating it in module docstrings where it matters. Phrase it generically — "nothing under altar may import the private host application (its infra adapters, private data-lake, etc.)" — rather than naming specific private packages.

Allowed references

Public, installable things are fine to name: standard library, third-party PyPI packages (google-cloud-bigquery, modal, kubernetes), public products (BigQuery, GCS), and other modules within altar. The line is simply: can a reader who only has this package follow it?

Markup: Markdown, not reStructuredText

The API reference is generated from these docstrings with mkdocstrings, which renders them as Markdown. So write docstring markup as Markdown:

• Inline code / symbol names use backticks: `ContainerTaskSpec`, `num_folds`. Do not use Sphinx cross-reference roles (:class:`ContainerTaskSpec`, :meth:`submit`, :data:`...`) — they are not Markdown, so they render as the literal text :class: in front of the name on the docs site.
• A structured parameter/returns block, when you want one, is a Google-style Args: / Returns: / Raises: section (mkdocstrings renders these into tables). Prose is equally fine — most docstrings here are prose.

The rendered pages are built under --strict in CI (docs.yml), so a broken nav entry or ::: identifier fails the build.