sphinx-pyrunblock

Fast, in-process embedding of live Python code output into your Sphinx docs. sphinx-pyrunblock runs each .. runblock:: example directly in a shared interpreter rather than spawning a subprocess per block — and it's backward compatible with sphinx-autorun: same runblock directive, same autorun_languages config shape, drop-in upgrade.

    .. runblock:: pycon

        >>> for i in range(5):
        ...    print(i)

Produces:

    >>> for i in range(5):
    ...    print(i)
    0
    1
    2
    3
    4

Installation

    $ pip install sphinx-pyrunblock

Enable the extension by adding it to the extensions list in conf.py:

    extensions.append("sphinx_pyrunblock")

See the full documentation for configuration (conf.py options, runfirst setup), per-block directive options (:numpy:, :scipy:, :smtb:, :precision:, :include:, :exclude:), and how errors are reported during a build.

Heritage

sphinx-pyrunblock began as a fork of sphinx-autorun by Hugo Osvaldo Barrera, itself descended from Vadim Gubergrits' original sphinxcontrib-autorun. See the full history for the complete lineage.