Metadata-Version: 2.4
Name: sphinx-pyrepl-web
Version: 0.2.0
Summary: A Sphinx extension for embedding pyrepl-web Python REPLs in documentation.
Keywords: sphinx,pyrepl,pyodide,repl
Author-email: Christian López Barrón <chris.gfz@gmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
License-File: LICENSE
Requires-Dist: sphinx>9
Requires-Dist: myst-parser ; extra == "docs"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: sphinx-pytest ; extra == "test"
Project-URL: Documentation, https://sphinx-pyrepl-web.readthedocs.io/
Project-URL: Home, https://github.com/chrizzFTD/sphinx-pyrepl-web
Project-URL: Issues, https://github.com/chrizzFTD/sphinx-pyrepl-web/issues
Project-URL: Repository, https://github.com/chrizzFTD/sphinx-pyrepl-web
Provides-Extra: docs
Provides-Extra: test

# sphinx-pyrepl-web

Sphinx extension to embed [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web) in documentation.

## Install

```bash
pip install sphinx-pyrepl-web
```

For development:

```bash
pip install -e ".[test,docs]"
```

## Usage

Add the extension to the target project's `conf.py`:

```python
extensions = [
    "sphinx_pyrepl_web",
]
```

Embed a REPL with the `py-repl` directive:

```rst
.. py-repl::

.. py-repl::
   :theme: catppuccin-latte
   :no-header:

.. py-repl::
   :src: setup.py
   :packages: numpy

.. py-repl::
   :no-header:

   >>> import math
   >>> math.sqrt(16)
```

### Directive options

All options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with the exception of `silent`: 

| Option | Description |
|--------|-------------|
| `:theme:` | Color theme (`catppuccin-mocha`, `catppuccin-latte`) |
| `:packages:` | Comma-separated PyPI packages to preload |
| `:repl-title:` | Title in the REPL header |
| `:src:` | Path to a Python startup script |
| `:replay:` | Replay `:src:` with interactive prompts instead of silent load |
| `:silent:` | Keep `:src:` silent even when combined with a directive body |
| `:no-header:` | Hide the header bar |
| `:no-buttons:` | Hide copy/clear buttons |
| `:readonly:` | Disable input |
| `:no-banner:` | Hide the Python version banner |

Python code within the `.. py-repl::` directive is written to `_static/pyrepl/` at build time and emitted as `replay-src`.

Optional Sphinx config:

```python
pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script
pyrepl_doctest_blocks = False  # default; see Docstring conversion below
pyrepl_autodoc_bootstrap = True  # default; silent :src: bootstrap for autodoc REPLs
```

### Docstring conversion

Converting doctest examples from docstrings into interactive REPLs is opt-in with `sphinx.ext.autodoc`:

```python
# conf.py
extensions = [
    "sphinx.ext.autodoc",
    "sphinx_pyrepl_web",
]
pyrepl_doctest_blocks = "autodoc"
```

|                   | `pyrepl_doctest_blocks` options     |
|-------------------|-------------------------------------|
| `False` (default) | Disable autodoc conversion          |
| `"autodoc"`       | Convert doctests found by autodoc   |
| `"all"`           | Transform every doctest block found |


|                  | `pyrepl_autodoc_bootstrap` options                                           |
|------------------|------------------------------------------------------------------------------|
| `True` (default) | Bootstrap REPL: in-tree modules via silent `:src:`, packages via `packages=` |
| `False`          | Replay doctest input only; documented names are not pre-defined              |

## Updating pyrepl-web

Since [chrizzFTD/pyrepl-web](https://github.com/chrizzFTD/pyrepl-web) is a fork, this sphinx extension vendors the JavaScript assets for easier distribution. To update them, run:

```bash
python scripts/vendor_repl.py
```

The `grill` branch is used by default. Use the `branch` argument to specify a different one:

```bash
python scripts/vendor_repl.py --branch custom/feature-branch
```

This requires [git](https://git-scm.com/) and [Bun](https://bun.sh/).

