Skip to content

Docstring and documentation conventions

altar is an independent, publishable package. Its docstrings ship inside the wheel and render on the docs site. A reader who has only installed the package, with no access to any host application or internal design document, must be able to understand every one of them.

The rule of thumb: explain the engineering, not where it came from. Keep every real rationale, such as why an interface exists, how paths combine, Kleene semantics, or why a call runs in a thread. Remove anything that only makes sense inside a particular private repository.

These conventions cover what a docstring may reference. Writing style covers how to write the prose itself; read it 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

altar must not import from any private host application. scripts/check_core_boundary.py, which the local gate runs, enforces it. Keep stating the rule in module docstrings where it matters, phrased generically, such as "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 test: 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`. Don't 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.