sphinx-pyodide

Sphinx extension to add a pyodide directive for embedding executable Python code blocks in documentation using Pyodide (Python in the browser via WebAssembly).

For full details and examples, refer to the documentation.

How to Use

Install with pip, uv, or similar:

pip install sphinx-pyodide

Enable the extension by including in your Sphinx conf.py:

extensions = ["sphinx_pyodide"]

The output blocks support light and dark mode. For best results, use a Sphinx theme with built-in dark mode support such as Furo or the PyData Sphinx Theme.

Use in documentation files. Build-time output is displayed as static output below each block. Interactive execution requires opt-in — click the Enable Interactive button in the note above the first block to load Pyodide and run blocks live in the browser.

.. pyodide::

    print("Hello from Pyodide!")
    import numpy as np
    print(np.array([1, 2, 3]))

Options

Development

Setup

Install development dependencies; install pre-commit hooks on first setup.

uv sync --dev
pre-commit install

Testing

Tests use sphinx.testing fixtures via pytest.

pytest tests/
pytest tests/ -k test_name
pytest tests/ --cov=src/sphinx_pyodide

Build Documentation

# One-time build
sphinx-build -b html docs/source docs/build

# Auto-reload with live preview (recommended for development)
sphinx-autobuild docs/source docs/build

Note: Pyodide blocks that install dependencies from local wheels require an HTTP server (file:// will not work due to CORS). Options are to build and serve with python -m http.server -d docs/build or serve with sphinx-autobuild.

Acknowledgments

Substantial portions of this code were developed with assistance from agentic AI coding tools (primarily ClaudeCode & OpenCode and associated models).

License

Apache 2.0