Skip to content

docs: add runnable Examples sections to public functions that lack them #1886

Description

@vprusso

The documentation build executes the Examples code blocks in docstrings (the ```python exec="1" blocks), so a runnable example doubles as documentation and a lightweight smoke test. Several public functions have no Examples section.

What to do

Add an Examples section with a short, runnable snippet, matching the existing style:

```python exec="1" source="above" result="text"
import numpy as np
from toqito.states import dicke

print(dicke(...))
```

Good targets (pick one or a few per PR):

  • toqito/measurement_ops/measure.py
  • toqito/states/dicke.py
  • toqito/state_props/has_symmetric_inner_extension.py
  • toqito/state_props/integral_relative_entropy.py
  • the cone builders in toqito/cones/ (e.g. geometric_mean_epi_cone.py)

Verifying

The example runs during the docs build:

uv sync --group docs
cd docs && uv run mkdocs build

Confirm the snippet runs without error and the printed output is sensible. Looking at an existing function's Examples section (e.g. toqito/channels/dephasing.py) is the easiest way to see the expected format.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions