Metadata-Version: 2.4
Name: sphinx-run
Version: 0.2.2
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

# Sphinxrun

SphinxRun 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
import textwrap


class Wrapper:
    """Wrapper class.

    .. run::

        from example import Wrapper

        d = Wrapper()

        with open("docs/source/lorem.txt") as f:
            text = f.read()
    """

    def wrap70(self, text):
        """Wrap text to 70 columns.

        .. run::

            output = d.wrap70(text)

            sphinxrun.show(output)
        """
        return textwrap.fill(text)
```

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 sphinxrun
# or
uv add --dev sphinxrun
```

Then add the extension to the sphinx configuration:

```py
   extensions = [
      ...
      "sphinxrun"
   ]
```

## Documentation

The documentation is hosted at: https://sphinxrun.readthedocs.io/en/latest/
