Documenting monoprop

This document describes the requirements, recommendations, and guides for writing documentation for monoprop, as well as details for contributing to and building the monoprop documentation.

Documentation structure

The documentation site lives in docs/ and is built with Fumadocs (Next.js). Content files are located under docs/content/docs/ and written in MDX (.mdx).

docs/
  content/
    docs/          # all documentation pages (.mdx)
      concepts/    # conceptual reference pages
      features/    # feature guides
  notebooks/       # Jupyter tutorial notebooks (converted to .md at build time)
  scripts/         # tooling: API generation, notebook conversion

The navigation order is controlled by docs/content/docs/meta.json.

Writing documentation pages

Page format

Every page must start with a YAML frontmatter block that provides title and description:

---
title: My page title
description: A short description shown in search results and link previews.
---

Page content goes here.

Pages are written in MDX, so standard Markdown syntax is fully supported alongside JSX components provided by Fumadocs UI.

Math

Inline math uses $…$ and display math uses $$…$$, rendered via KaTeX:

The eigenvalue equation is $H |\psi\rangle = E |\psi\rangle$.

$$
Z = \text{tr}\!\left(e^{-\beta H}\right)
$$

Citations

References are defined in docs/bibliography.bib. Cite them with [@key]:

This follows the approach of [@smith2024].

Cross-references to the API

Link to any documented Python symbol with the mkdocstrings-style reference syntax [Symbol][] — the same form used inside docstrings (see below). The symbol resolves to its API-reference page automatically, so you never hard-code an /api/... URL:

The top-level classes are [MajoranaPropagator][] and [PauliPropagator][].

• Do not wrap the name in backticks in the [Symbol][] form: write [MajoranaPropagator][], not [`MajoranaPropagator`][]. The renderer adds the code-span styling for you (backticks would split the reference and stop it resolving).

• Bare names must be unambiguous. [MajoranaPropagator][] works because the name is unique across the public API. A name defined in more than one place — a second module, or a member that several classes each document — is dropped from the bare-name index and will not resolve. Give it a fully-qualified path as an explicit target, which is also how you set custom display text:

  See [the operator class][monoprop.majorana.MajoranaOperator] for details.

  Member names are the common case. The propagators document their shared surface on each front-end, so build_graph, evolved_operator, parameter_mapping, update_initial_operator, n_gates, graph_layers and size each name three symbols; terms, isclose and get_majorana_operator are likewise shared across the operator classes, and num_modes across both families. Always qualify these:

  Extend the graph with
  [build_graph][monoprop.monomial_propagator.MonomialPropagator.build_graph].

• Unresolved references are left as literal text and print a remark-xref: unresolved cross-reference … warning during the build, so typos surface instead of silently producing a broken link.

Links to other documentation pages are still ordinary Markdown links, e.g. [Building from source](/building).

Code examples and doctests

Python code blocks in documentation pages are validated as doctests. Write them using the standard >>> REPL style so they are picked up automatically:

```python
>>> from monoprop import MonomialPropagator
>>> mp = MonomialPropagator(...)
```

Run doctests across all docs pages (excluding tutorials) with:

just doctest-docs

Python API reference

The API reference is auto-generated from Python docstrings using griffe and fumadocs-python. Do not edit files under docs/content/docs/api/ directly — they are overwritten every time the generator runs.

To update the API reference after changing docstrings, regenerate it:

just gen-api

Python docstrings must follow Google style:

def my_function(x: int) -> str:
    """Short one-line summary.

    Args:
        x: Description of x.

    Returns:
        Description of the return value.

    Example:
        >>> my_function(1)
        '1'
    """

Docstrings may cross-reference other symbols with the same [Symbol][] / [Display][fully.qualified.path] syntax described in Cross-references to the API; griffe resolves them into links when the reference is regenerated.

Inside a class docstring a bare [name][] only reaches that class's own members. Inherited members are rendered on the subclass page but are not in the cross-reference index, so a subclass docstring pointing at a base-class method must spell out the full path — [expectation_value][monoprop.monomial_propagator.MonomialPropagator.expectation_value], not [expectation_value][].

Tutorial notebooks

Tutorials live as Jupyter notebooks in docs/notebooks/. They are executed and converted to MDX at build time; a failing cell fails the build, so notebooks act as end-to-end integration tests.

To regenerate the tutorial pages from the notebooks:

just gen-notebooks

Building locally

Development server (recommended)

Building it locally requires npm, the Node.js package manager. Please follow the instructions provided on the website to install it. In the DevContainer, you can install it using apt command:

sudo apt update
sudo apt install -y npm

The fastest way to preview changes is the live-reloading dev server. It regenerates the API reference and notebooks once, then watches for file changes:

just serve-docs

Open http://localhost:3000 in your browser. Page edits in docs/content/docs/ appear immediately without a restart.

Full static build

To reproduce the exact build that runs in CI — including all doctests — run:

just build-docs

This executes the following steps in order:

The rendered static site is written to docs/out/.

Running individual steps

just docs-install   # install / update npm dependencies
just gen-api        # regenerate API reference only
just gen-notebooks  # regenerate tutorial pages only
just doctest-py     # run Python docstring doctests
just doctest-docs   # run documentation page doctests