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].

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'
    """

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)

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