sphinx-pyrepl-web¶

Sphinx extension to embed pyrepl-web in documentation.

Install¶

pip install sphinx-pyrepl-web

For development:

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

Usage¶

Add the extension to the target project’s conf.py:

extensions = [
    "sphinx_pyrepl_web",
]

Embed a REPL with the py-repl directive:

.. 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¶

Most options drive pyrepl-web’s attributes, with a few exceptions unique to this extension:

Option	Description	`pyrepl-web` attr?
`: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	❌
`:strip-prompts:`	Strip `>>>` / `...` prefixes from directive body	❌
`:no-header:`	Hide the header bar	✅
`:no-buttons:`	Hide copy/clear buttons	✅
`:readonly:`	Disable input	✅
`:no-banner:`	Hide the Python version banner	✅

Directive body content (inline Python in the .. py-repl:: block) is also extension-only: it is written to _static/pyrepl/ at build time and emitted as replay-src.

Optional Sphinx config:

pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script

Updating pyrepl-web¶

Since chrizzFTD/pyrepl-web is a fork, this sphinx extension vendors the JavaScript assets for easier distribution. To update them, run:

python scripts/vendor_repl.py

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

python scripts/vendor_repl.py --branch cursor/repl-startup-replay-2e3f

This requires git and Bun.

Examples¶

Basic REPL¶

.. py-repl::

Light theme, minimal¶

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

Startup script¶

The :src: option loads a Python script into the REPL namespace. If the script defines a setup() function, its output is shown when the REPL starts.

.. py-repl::
   :src: _static/setup.py

The startup script:

message = "Hello from the startup script!"


def setup():
    print(message)
    print("Try: message")

Replay session¶

Inline directive content is replayed with >>> prompts, syntax highlighting, and live output. Doctest-style >>> / ... prefixes and bare ... block terminators are stripped automatically.

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

   >>> x = 2 + 2
   >>> print(f"{x=}")
   >>> x * 10
   >>> class Foo:
   ...     x = 1
   ...
   >>> Foo()

Combine a silent bootstrap file with a visible replay body:

.. py-repl::
   :src: _static/setup.py
   :no-header:

   >>> print(message)

Use :replay: on :src: to replay a file with prompts instead of silent load:

.. py-repl::
   :src: _static/replay_demo.py
   :replay:
   :no-header:
   :no-banner:

The replay script:

greeting = "Hello from replay mode"
print(greeting)
greeting.upper()