Metadata-Version: 2.4
Name: sphinx-pyodide
Version: 0.1.1
Summary: Sphinx extension to add pyodide directive
Project-URL: Documentation, https://rlskoeser.github.io/sphinx-pyodide/
Project-URL: Homepage, https://github.com/rlskoeser/sphinx-pyodide
Project-URL: Source, https://github.com/rlskoeser/sphinx-pyodide
Project-URL: Tracker, https://github.com/rlskoeser/sphinx-pyodide/issues
Author-email: Rebecca Sutton Koeser <rebecca.s.koeser@princeton.edu>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: documentation,interactive,pyodide,sphinx,wasm
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: docutils>=0.20
Requires-Dist: pygments>=2.19.2
Requires-Dist: sphinx>=8.0.0
Description-Content-Type: text/markdown

# sphinx-pyodide

Sphinx extension to add a `pyodide` directive for embedding executable Python code blocks in documentation using [Pyodide](https://pyodide.org/) (Python in the browser via WebAssembly).

For full details and examples, refer to the [documentation](https://rlskoeser.github.io/sphinx-pyodide/).

## How to Use

Install with `pip`, `uv`, or similar:

```bash
pip install sphinx-pyodide
```

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

```python
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](https://github.com/pradyunsg/furo) or the [PyData Sphinx Theme](https://github.com/pydata/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.

```rst
.. pyodide::

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

### Options

| Option          | Type   | Description                                                                                           |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `:packages:`    | string | Comma-separated PyPI packages to load (e.g., `numpy, pandas`). Local `.whl` files are also supported. |
| `:editable:`    | flag   | Allow users to edit the code before running.                                                          |
| `:output:`      | string | Static output displayed in the output panel until interactive execution is enabled.                   |
| `:show-errors:` | flag   | Display runtime errors in the live browser output.                                                    |
| `:setup-code:`  | string | Python code to run once before the main block (e.g., imports).                                        |

## Development

### Setup

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

```bash
uv sync --dev
pre-commit install
```

### Testing

Tests use `sphinx.testing` fixtures via `pytest`.

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

### Build Documentation

```bash
# 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
