https://github.com/yongrenjie/sphinx-exec-directive

Sphinx extension to run Python code blocks and display the output.
https://github.com/yongrenjie/sphinx-exec-directive

python sphinx sphinx-extension

Last synced: 3 days ago
JSON representation

Sphinx extension to run Python code blocks and display the output.

• Host: GitHub
• URL: https://github.com/yongrenjie/sphinx-exec-directive
• Owner: yongrenjie
• License: mit
• Created: 2021-04-20T22:21:08.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-03-13T16:58:16.000Z (8 months ago)
• Last Synced: 2024-04-14T07:11:13.368Z (7 months ago)
• Topics: python, sphinx, sphinx-extension
• Language: Python
• Homepage: https://yongrenjie.github.io/sphinx-exec-directive/
• Size: 283 KB
• Stars: 4
• Watchers: 2
• Forks: 3
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
# sphinx-exec-directive

`sphinx-exec-directive` allows you to write code blocks in reStructuredText files, execute them during Sphinx compilation, and display the output directly within the generated documentation.

The 'default' code language is Python, but there is some limited support for other languages right now (see the [extension documentation](https://yongrenjie.github.io/sphinx-exec-directive) for more info).

If you want a particular language to be added, please feel free to raise an issue!

This is based very strongly on [matplotlib's `plot_directive` extension](https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html?highlight=plot%20directive#module-matplotlib.sphinxext.plot_directive), but is used for running code instead of generating plots.

## Installation

```

pip install sphinx-exec-directive

```

Then, inside your Sphinx `conf.py`, add `sphinx_exec_directive` to your list of extensions (note: underscores not hyphens).

```

extensions = [

    sphinx_exec_directive,

    # other extensions...

]

```

## Basic example

```

.. exec::

   

   print(1 + 1)

```

Place the above into your RST file and Sphinx will generate two literal blocks when compiling, one with the 'input' source code, and one with the captured stdout:

![Example sphinx-exec-directive output](https://i.stack.imgur.com/5sVSS.png)

## Documentation

For further details and usage examples, please see the [documentation](https://yongrenjie.github.io/sphinx-exec-directive).

It contains quite a few exec directives, so you get to see some in the wild!