sphinxcontrib-repl 0.4.1

Sphinx Extension - Directives to auto-evaluate Python code-blocks

==========================================================================
sphinxcontrib-repl - Directives to auto-evaluate Python code-blocks
==========================================================================

|pypi| |pypi-status| |pypi-pyvers| |github-license| |github-status|

.. |pypi| image:: https://img.shields.io/pypi/v/sphinxcontrib-repl
:alt: PyPI
.. |pypi-status| image:: https://img.shields.io/pypi/status/sphinxcontrib-repl
:alt: PyPI - Status
.. |pypi-pyvers| image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-repl
:alt: PyPI - Python Version
.. |github-license| image:: https://img.shields.io/github/license/sphinx-contrib/repl
:alt: GitHub License
.. |github-status| image:: https://img.shields.io/github/workflow/status/sphinx-contrib/repl/Run%20Tests
:alt: GitHub Workflow Status

``sphinxcontrib-repl`` is an extension to `Sphinx <https://www.sphinx-doc.org/>`_
document generator tool. The extension introduces ``repl`` and ``repl-quiet``
directives to run Python REPL interpreters during Sphinx builds the
documentation. The content of the directives will be automatically evaluated
line-by-line in the interpreter, and ``repl`` blocks will add what would be
printed on the interpreter to the output document.

--------
Contents
--------

- `Installation <Installation_>`_
- `Basic Usage <Basic Usage_>`_
- `Matplotlib Integration <Matplotlib Integration_>`_
- `Options <Options_>`_

------------
Installation
------------

Install from PyPI:

.. code-block::

pip install sphinxcontrib-repl

Then, inside your Sphinx ``conf.py``, add ``sphinxcontrib.repl`` to your list of extensions:

.. code-block:: Python

extensions = [
"sphinxcontrib.repl",
# other extensions...
]

-----------
Basic Usage
-----------

To run Python code in the interpreter, list the code in a ``repl`` block:

.. code-block:: rst

.. repl::

2*3+4
x=5
f"{x=}"

First of such block will invoke a dedicated Python interpreter process, which will continue
to run in the background for each RST document until the document is fully parsed. The above block
of code will produce the following document block:

.. code-block:: python

>>> 2*3+4
10
>>> x=5
>>> f"{x=}"
'x=5'

As the interpreter process will run continuously, the variables will carry between blocks.
For example, after the above ``repl`` block, the variable ``x`` may be used in any
subsequent ``repl`` blocks (unless you delete it):

.. code-block:: rst

.. repl::

x+4

will produce:

.. code-block:: python

>>> x+4
9

A REPL block may contain (potentially nested) condition/loop statements:

.. code-block:: rst

.. repl::

for i in range(5):
if i>2:
i+1

outputs

.. code-block:: python

>>> for i in range(5):
... if i>2:
... i+1
...
4
5

Note that a trailing empty line to terminate the indented block will be inserted
automatically.

To hide nuisance operations (e.g., importing common libraries),
use ``repl-quiet`` block:

.. code-block:: rst

.. repl-quiet::

import numpy as np

After this block, the Numpy package is loaded onto the interpreter, but the import
line will not be printed in the document.

--------------------------
Matplotlib Integration
--------------------------

Plotting ``matplotlib`` figures in the REPL interpreter process yields the figures
to be automatically exported to the document:

.. code-block:: rst

.. repl::

import numpy as np
from matplotlib import pyplot as plt

plt.plot(np.random.randn(100))
plt.figure()
plt.plot(np.random.randn(100))
plt.show()

The above RST ``repl`` block generates the following Python code snippet and the
figure images:

.. code-block:: python

>>> import numpy as np
>>> from matplotlib import pyplot as plt
>>> plt.plot(np.random.randn(100))
[<matplotlib.lines.Line2D object at 0x0000025C046CCDF0>]
>>> plt.figure()
<Figure size 800x400 with 0 Axes>
>>> plt.plot(np.random.randn(100))
[<matplotlib.lines.Line2D object at 0x0000025C0471A7F0>]
>>> plt.show()

.. image:: docs/imgs/mpl_0_1.svg

.. image:: docs/imgs/mpl_0_2.svg

To hide the Python code, use the ``repl-quiet`` directive, which will only display
the figures:

.. code-block:: rst

.. repl-quiet::

plt.plot(np.random.randn(100))
plt.title('plotted in repl-quiet')
plt.show()

This code prints only the image:

.. image:: docs/imgs/mpl_1_1.svg

--------------------------
Options
--------------------------

Visibility Control Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, ``repl`` directive shows everything and ``repl-quiet`` hides everything. It is possible
to control the visibility of input and output lines in the ``repl`` directive with the following
directive options and magic comments.

================= ===================== ===========
Directive Magic comment Description
================= ===================== ===========
``:hide-input:`` ``#repl:hide-input`` Hide input (directive option value: ``true`` or ``false``)
``:hide-output:`` ``#repl:hide-output`` Hide output (directive option value: ``true`` or ``false``)
\ ``#repl:show-input`` Show input
\ ``#repl:show-output`` Show output
\ ``#repl:hide`` Hide both input and output
\ ``#repl:show`` Show both input and output
================= ===================== ===========

For example,

.. code-block:: rst

.. repl::
:hide-output: true

'only shown as input'

outputs

.. code-block:: rst

>>> 'only shown as input'

and does not show the echoed output string.

To provide a fine-grain control, there are 6 magic comments to switch the visibility. They can be applied
only to a line (as an inline comment) or toggle for the remainder of the directive context.

.. code-block:: rst

.. repl::

#repl:hide-input
'no input'
'show input' #repl:show
'no input again'
#repl:show-input

#repl:hide-output
'no output'
'show output' #repl:show
'no output again'
#repl:show-output


outputs

.. code-block:: rst

'no input'
>>> 'show input'
'show input'
'no input again'
>>>
>>> 'no output'
>>> 'show output'
'show output'
>>> 'no output again'

Matplotlib Options
^^^^^^^^^^^^^^^^^^

The Matplotlib figure properties can be customized by specifying the following options either as
the extension options (in the Sphinx ``conf.py`` file) or as the directive options. Be aware that the
directive options persist in the subsequent directives.

In addition to the figure options, any Matplotlib rc settings could be changed via ``rc_params`` option.
Consult `the default matplotlibrc file <https://matplotlib.org/stable/tutorials/introductory/customizing.html#the-matplotlibrc-file>`_
for possible entries. The exposed options are of the ``savefig`` group, except for ``figsize`` which
sets ``figure.figsize`` option in the REPL interpreter.

======================== ===================== ============ ===========
Extension Directive Default Description
======================== ===================== ============ ===========
``repl_mpl_disable`` ``False`` ``True`` to disable matplotlib support
``repl_mpl_dpi`` ``96`` raster dots per inch
``repl_mpl_format`` ``svg`` output image format (default is pdf for latex) ``{png, ps, pdf, svg}``
``repl_mpl_figsize`` ``:mpl-figsize:`` ``6.4, 4.8`` figure size in inches
``repl_mpl_facecolor`` ``:mpl-facecolor:`` ``white`` figure face color
``repl_mpl_edgecolor`` ``:mpl-edgecolor:`` ``white`` figure edge color
``repl_mpl_bbox`` ``:mpl-bbox:`` ``standard`` bounding box ``{tight, standard}``
``repl_mpl_pad_inches`` ``:mpl-pad-inches:`` ``0.1`` padding to be used, when ``bbox`` is set to ``tight``
``repl_mpl_transparent`` ``:mpl-transparent:`` ``False`` whether figures are saved with a transparent
``repl_mpl_rc_params`` ``:mpl-rc-params:`` other ``rcParams`` options
======================== ===================== ============ ===========

Example of extension options in ``conf.py``:

.. code-block:: python

repl_mpl_disable = False
repl_mpl_figsize = (8, 4)
repl_mpl_dpi = 96
repl_mpl_format = "svg"
repl_mpl_facecolor = "gray"
repl_mpl_edgecolor = "black"
repl_mpl_bbox = "tight"
repl_mpl_pad_inches = 0.1
repl_mpl_transparent = False
repl_mpl_rc_params = {"lines.marker": "o"}


Example of directive options:

.. code-block:: rst

.. repl-quiet::
:mpl-figsize: 6, 4
:mpl-facecolor: orange
:mpl-edgecolor: red
:mpl-bbox: standard
:mpl-pad-inches: 0.1
:mpl-transparent: False
:mpl-rc-params: {"lines.marker": "x", "lines.markersize": 3}

plt.plot(np.random.randn(100))
plt.title('plotted in repl-quiet')
plt.show()

Image Options
^^^^^^^^^^^^^

All of the options of the ``image`` directive, except for ``target`` (since target
image is generated by the REPL process). Currently, these options applies to the
Matplotlib figure images.

================== ===========
Directive Description
================== ===========
``:image-alt:`` Alternate text: a short description of the image
``:image-height:`` The desired height of the image
``:image-width:`` The width of the image
``:image-scale:`` The uniform scaling factor of the image
``:image-align:`` The alignment of the image
``:image-class:`` Set a "classes" attribute value on the doctree element generated by the directive
================== ===========

Table Options
^^^^^^^^^^^^^

By specifying ``:table-ncols:`` directive option to a positive integer, the Matplotlib figures will be
shown in a table with as many columns.

================== ======================================================================================
Directive Description
================== ======================================================================================
``:table-ncols:`` Number of columns (if 0 or omitted, no table will be used)
``:table-align:`` The horizontal alignment of the table {``left``, ``center``, or ``right``}
``:table-width:`` Sets the width of the table to the specified length or percentage of the line width
``:table-widths:`` Explicitly set column widths. Specifies relative widths if used with the width option.
{``auto``, ``grid``, or a list of integers}
``:table-class:`` Set a "classes" attribute value on the doctree element generated by the directive
================== ======================================================================================