Metadata-Version: 2.4
Name: sphinxcontrib-run
Version: 0.3.0
Summary: Dynamically generated content for sphinx documentations
License-Expression: BSD-2-Clause
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.rst
Requires-Dist: sphinx>=8
Provides-Extra: dev
Requires-Dist: esbonio; extra == "dev"
Requires-Dist: pyproject-fmt; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: doc
Requires-Dist: furo; extra == "doc"
Dynamic: license-file

# 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:

```py
"""
.. 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:

![rendered doc screenshot](example.jpg)

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

## Installation

Install the package:

```sh
pip install sphinxcontrib-run
```

Then add the extension to the sphinx configuration:

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

## Documentation

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