Documentation

Documentation#

A good documentation is essential. You can contribute by improving existing docs or adding new material.

1. Docstrings#

Every public function and class should have a docstring. We use NumPy-style docstrings parsed by sphinx.ext.napoleon. The API reference is built automatically with Sphinx and hosted on Read the Docs.

You can create cross-references between docstrings using Sphinx roles. For example:

def add(a, b):
    """Add two numbers.

    See :func:`sum` for a more general function.
    See :class:`Addition` for more information.

    Parameters
    ----------
    a : float
        First number.
    b : float
        Second number.

    Returns
    -------
    float
        The sum of *a* and *b*.
    """
    return a + b

2. Sphinx documentation#

We use MyST Parser for Markdown (.md) and reStructuredText (.rst) support. With nbsphinx, we also include Jupyter notebooks (.ipynb) directly in the docs.

The documentation lives in docs/. Tutorial notebooks are in docs/source/tutorials/.

When contributing tutorials:

  • Provide clear explanations and code examples.

  • Run the notebook locally before committing and commit it with up-to-date outputs.

  • Do not clear outputs before committing if they are needed for the reader to follow the tutorial.

  • Notebooks are not re-executed automatically in CI. The committed output is what appears in the published docs.

Integration tutorials (external packages)#

We explicitly welcome tutorials that show how to use ggml-ot together with other Python packages, especially from the scverse ecosystem (for example Scanpy/scvi-tools-style workflows).

For integration tutorials, include:

  • The target package(s) and intended user workflow.

  • The handoff points between tools (inputs/outputs, data structures, key fields).

  • A minimal reproducible example that users can run end-to-end.

  • Notes on limitations, version assumptions, or optional dependencies.

To ensure docs build correctly, install docs dependencies and run the strict docs build:

poetry install --with docs
make docs-strict

make docs-strict runs sphinx-build -W which treats Sphinx warnings as errors, while make docs ignores warnings. To re-execute all tutorial notebooks during the build, you can use make docs-with-nbsphinx (very slow, only for major changes).

For a quick local preview while editing, serve the built docs:

python -m http.server 8000 -d docs/build/html

In VS Code Remote-SSH, this usually triggers a forwarded-port popup so you can open the docs in your browser directly.