.. role:: python(code)
   :language: python

.. role:: rst(code)
   :language: rst

sphinxcontrib-run documentation
===============================

sphinxcontrib-run registers a new :rst:dir:`.. run:: <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
-------

.. literalinclude:: example.py

renders as:

.. automodule:: example
   :members:


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

Install the package:

.. code:: shell

   pip install sphinxcontrib-run
   # or
   uv add --dev sphinxcontrib-run

Then add the extension to the sphinx configuration:

.. code:: python

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

Usage
-----

.. rst:directive:: run

   Directive to execute code.

   The interpreter persists through the scope of a document, so imports and global variables can be reused across multiple directives.
   More specifically, the scope corresponds to a single `.rst` file (or its parent when included or generated by autodoc).

   .. note::

      When using autodoc, the `:member-order: <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-member-order>`_ option will influence the order in which directives are execute.

   The code can generate content to insert at the position of the directive by printing to the standard output.

   .. rubric:: Options

   .. rst:directive:option:: group
      :type:

      Specify a group name.
      The commands from each group are run in separate processes.

   .. rst:directive:option:: hidden
      :type:

      The content printed by the commands to the standard output will be ignored.