Python docs

A high-level overview of writing and previewing the Rerun Python documentation.

How docs coverage works

The set of symbols documented at ref.rerun.io/docs/python/ is derived automatically from the public-API conventions in the SDK source. There is no hand-curated index to maintain in lockstep — adding a new public symbol via the conventions below is sufficient to surface it in the docs.

A symbol is considered public (and gets documented) when any of the following applies in its module:

It is listed in the module's __all__.
It is re-exported via from ._x import Foo as Foo (PEP 484 redundant alias).
It is defined in-file with a non-underscore name and the module does not define __all__.

The conventions are detected by griffe plus the griffe-public-redundant-aliases extension (configured in mkdocs.yml).

Adding a new public symbol

Re-export from a subpackage: add from ._impl import Foo as Foo to the relevant __init__.py. The redundant as Foo form matters — it is also required by pyright's strict-mode reportPrivateUsage rule.
Define in-file in a single-file module: include "Foo" in the module's __all__ (e.g., see rerun_sdk/rerun/urdf.py, rerun_sdk/rerun/server.py).
Stand up a Track A page for a brand-new subpackage: add a row to DOCUMENTED_PACKAGES in docs/gen_common_index.py mapping the dotted path to its nav title (e.g., "rerun.foo": ("Foo",) for a top-level entry, or "rerun.bar.baz": ("Bar", "Baz") to nest it under "Bar"). The first build will tell you about every public symbol so you can decide what (if anything) belongs in EXPLICIT_DOC_EXCLUDES.
Group symbols on the landing page: add to CURATED_GROUPS in docs/gen_common_index.py. Curated groups are tables only — they do not gate coverage and may safely duplicate symbols already listed by Track A.

Hiding a public symbol from docs

Add it (per package) to EXPLICIT_DOC_EXCLUDES in docs/gen_common_index.py with an inline comment explaining why. Each entry is a deliberate decision; unexplained entries get rejected in code review.

What the build validates

pixi run py-docs-build fails (and CI fails) on any of:

A new top-level subpackage or module under rerun_sdk/rerun/ — or a new nested subpackage (a directory with __init__.py) under any documented package — that is neither in DOCUMENTED_PACKAGES nor in EXCLUDED_FROM_TRACK_A. This is the freshness check that prevents new modules from going silently undocumented.
A DOCUMENTED_PACKAGES or EXCLUDED_FROM_TRACK_A entry that no longer exists on disk (catches renames and removals).
A DOCUMENTED_PACKAGES entry whose module has no public surface (no __all__, no redundant aliases, no in-file definitions).
A DOCUMENTED_PACKAGES entry whose entire public surface is in EXPLICIT_DOC_EXCLUDES (the page would emit members: [], which is undefined in mkdocstrings).
A CURATED_GROUPS entry that references a symbol that doesn't exist — catches stale entries when symbols are renamed or removed.

Known limitations

PEP 562 __getattr__ aliases (used for deprecated re-exports) are invisible to static analysis. To document such a name, expose it via a real redundant-alias re-export and accept the validator's prompt.
Dynamic __all__ constructions (e.g., __all__ = list(SOMETHING)) are not supported; keep __all__ a static list/tuple of string constants.

Getting started with docs

Serving the docs locally

This will watch the contents of the rerun_py folder and refresh documentation live as files are changed.

pixi run py-docs-serve

How versioned docs are generated and served

Our documentation is versioned with releases and generated via mkdocs. The mkdocs dependencies are managed via uv (see the docs dependency group in pyproject.toml).

The documentation exists as bucket on GCS which is hosted on the https://ref.rerun.io domain.

Every commit that lands to main will generate bleeding edge documentation as HEAD. Behind the scenes, a GitHub action is running pixi run py-docs-build, and uploading the result to GCS at docs/python/main.

Releases will push to a version instead: docs/python/0.23.3

4.4 KiB Raw Permalink Blame History