sphinx-pyrepl-web

Sphinx extension to embed pyrepl-web in documentation.

Install

pip install sphinx-pyrepl-web

Usage

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

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

All options drive pyrepl-web's attributes:

Sphinx options

Enable doctest style examples conversion into pre-configured interactive REPLs with:

pyrepl_doctest_blocks:

pyrepl_autodoc_packages:

Optional when using :project::

Local wheels

Unreleased package wheels can be available in the REPL by building them under Sphinx's html_static_path, or by using :project: to build automatically at doc-build time.

All options combined:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx_pyrepl_web",
]

html_static_path = ["_static"]

pyrepl_doctest_blocks = "autodoc"
pyrepl_autodoc_packages = ":project:"

For a monorepo or non-default layout, point at the package root explicitly:

pyrepl_autodoc_packages = ":project:"
pyrepl_project_root = ".."

When the REPL needs the project wheel plus additional packages, combine them in one list:

pyrepl_autodoc_packages = ":project:, numpy"

The same :project: sentinel works in directive options:

.. py-repl::
   :packages: :project:, numpy