sphinxcontrib-run

sphinxcontrib-run registers a new .. run:: directive to execute code dynamically while building a sphinx documentation. It can be used to generate documentation artifacts such as figures or to insert dynamic content.

Example:

"""
.. run::

    from example import square_text_50

    lorem = (
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        + " Pellentesque faucibus vestibulum est id consequat."
        + " Cras sed enim sed ex maximus blandit."
    )
"""


def square_text_50(text):
    """Wrap text to 40 columns.

    .. run::

        print("::")
        print("")
        for line in square_text_50(lorem):
            print("    " + line)
        print("")
    """
    for i in range(0, len(text), 50):
        yield text[i : i + 50]

renders as:

Note: The environement persists across calls within the scope of a document.

Installation

Install the package:

pip install sphinxcontrib-run

Then add the extension to the sphinx configuration:

   extensions = [
      ...
      "sphinxcontrib.run"
   ]

Documentation

The documentation is hosted at: https://sphinxcontrib-run.readthedocs.io/en/latest/