writing-docstrings

Files (1)

• SKILL.md

SKILL.md (first lines)

# Writing Docstrings for Quarto / quartodoc

The API site at `docs/api/**` is generated by **quartodoc** from Python docstrings. Whether your code shows up well in the rendered site depends entirely on how you write them. This skill is the contract.

## TL;DR — the canonical form

```python
def render_code(experiment: SimulationExperiment, format: str = "jax") -> str:
    """Render the simulator code for *experiment* without executing it.

    Useful for debugging or for running the kernel outside TVBO. Supported
    formats are listed in [`tvbo.codegen.registry`](../codegen/registry.qmd).

    Args:
        experiment: The `SimulationExperiment` to render.
        format: Backend identifier (e.g. `"jax"`, `"tvb"`, `"pyrates"`).
            Defaults to `"jax"`.

    Returns:
        The rendered source code as a single string.

    Raises:
        ValueError: If *format* is not a registered backend.

    Examples:
        >>> code = render_code(exp, format="jax")
        >>> "def integrate" in code
        True
    """
```

That's the shape every docstring should approximate. The rules behind it:

## 1. Style is Google

The quartodoc config in `docs/api/_quartodoc_config.yml` sets `parser: google`. Use `Args:` / `Returns:` / `Raises:` / `Yields:` / `Examples:` blocks — **not** NumPy's `Parameters\n----------\n` underline form.

Google style is also less line-noise than NumPy and renders predictably as parameter tables in the Quarto site.

## 2. Type info goes on the **signature**, not in the docstring

```python
# ✗ Wrong — type duplicated in docstring
def foo(x):
    """Args:
        x (int): The thing.
    """

# ✓ Right — type on signature only
def foo(x: int) -> str:
    """Args:
        x: The thing.

    Returns:
        Description (no type — quartodoc reads it from `-> str`).
    """
```

Quartodoc displays the type from the annotation. Repeating it in the docstring desyncs over time and clutters the rendered table.

Exception: if a parameter is `Any`, `object`, or accepts heterogenous inputs, document the accepted forms in prose.

## 3. The body is **markdown**

Inside the docstring, write CommonMark/Quarto-flavored markdown:

- Backticks for code: `` `SimulationExperiment` ``, `` `from_db()` ``
- Links: `[CodeGen](../codegen/index.qmd)` for cross-references
- Lists, bold/italic, code blocks — all work
- Math: `$\dot{x} = -\gamma x$` inline, `$$ … $$` block

Quarto's renderer processes the body as markdown after quartodoc lifts the parameter blocks into tables.

## 4. First line is a one-sentence summary

Imperative, period-terminated, fits on one line. This becomes the entry in the module's summary table.

```python
"""Render a SimulationExperiment to YAML."""        # ✓
"""Renders a SimulationExperiment to YAML"""        # ✗ (no period, "Renders" not imperative)
"""This function renders a SimulationExperiment.""" # ✗ (filler words)
```

After a blank line, free-form prose can elaborate.

## 5. `Args:` block — only required when there are parameters

Each parameter gets its own line. Indent continuation lines by 4 spaces.

```python
def foo(x: int, y: str = "z", *args, **kwargs):
    """Summary.

    Args:
        x: Description.
        y: Description that spans
            multiple lines — indent the continuation by 4 spaces.
        *args: Positional varargs (document if meaningful).
        **kwargs: Forwarded to `something.else()`.
    """
```

Skip `self` / `cls`. Don't write `Args:` at all when the function takes no documented parameters.

**Never** group multiple parameter names on one line — `foo, bar: Both are ...` makes quartodoc emit a warning and the entry won't render correctly. Give each parameter its own line, even if the body is duplicated:

```python
# ✗ Wrong — quartodoc can't parse this
Args:
    edge_cmap, node_cmap: Matplotlib colormap names.

# ✓ Right
Args:
    edge_cmap: Matplotlib colormap name for edges.
    node_cmap: Matplotlib colormap name for nodes.
```

## 6. `Returns:` — describe what comes back

From virtual-twin/tvbo, EUPL-1.2.

More from virtual-twin/tvbo