=========
runpython
=========
This directive executes snippets of code inserted and add
the output to the documentation, as plain text or even RST format.
Usage
=====
In *conf.py*:
::
extensions = [ ...
'sphinx_runpython.runpython',
]
Documentation means many examples which needs to be updated when a change
happen unless the documentation runs the example itself and update its output.
That's what this directive does. It adds as raw text whatever comes out
throught the standard output.
One example:
::
.. runpython::
:showcode:
import os
for i, name in enumerate(os.listdir(".")):
print(i, name)
Which gives:
.. runpython::
:showcode:
import os
for i, name in enumerate(os.listdir(".")):
print(i, name)
The output can also be compiled as RST format and the code can be hidden.
It is useful if the documentation is a copy/paste of some external process
or function. This function can be directly called from the documentation.
The output must be converted into RST format. It is then added to the
documentation. It is quite useful to display the version of some installed
modules.
.. sidebar:: runpython and rst
::
.. runpython::
:rst:
import pandas, numpy, sphinx
for i, mod in [sphinx, pandas, numpy]:
print("* version of *{0}*: *{1}*".format(
getattr(mod, "__name__"), getattr(mod, "__version__"
))
.. runpython::
:rst:
import os
for i, name in enumerate(os.listdir(".")):
print("* file **{0}**: *{1}*".format(i, name))
If the code throws an exception (except a syntax error),
it can be caught by adding the option ``:exception:``.
The directive displays the traceback.
.. runpython::
:showcode:
:exception:
import os
for i, name in enumerate(os.listdir("not existing")):
pass
The directive can also be used to display images
with a tweak however. It consists in writing *rst*
code. The variable ``__WD__`` indicates the local
directory.
.. runpython::
:showcode:
print('__WD__=%r' % __WD__)
Applied to images...
.. sidebar:: runpython and image
::
.. runpython::
:rst:
import matplotlib.pyplot as plt
fig, ax = plt.subplots(1, 1, figsize=(4, 4))
ax.plot([0, 1], [0, 1], '--')
fig.savefig(os.path.join(__WD__, "oo.png"))
text = ".. image:: oo.png"
print(text)
The image needs to be save in the same folder than
the *rst* file.
.. runpython::
:rst:
import matplotlib.pyplot as plt
fig, ax = plt.subplots(1, 1, figsize=(4, 4))
ax.plot([0, 1], [0, 1], '--')
fig.savefig(os.path.join(__WD__, "oo.png"))
text = ".. image:: oo.png\n :width: 201px"
print(text)
Option ``:toggle:`` can hide the code or the output or both
but let the user unhide it by clicking on a button.
.. sidebar:: runpython and image
::
.. runpython::
:showcode:
:toggle: out
for i in range(0, 10):
print("i=", i)
.. runpython::
:showcode:
:toggle: out
for i in range(0, 10):
print("i=", i)
The last option of *runpython* allows the user to keep
some context from one execution to the next one.
.. sidebar:: runpython and context
::
.. runpython::
:showcode:
:store:
a_to_keep = 5
print("a_to_keep", "=", a_to_keep)
.. runpython::
:showcode:
:restore:
a_to_keep += 5
print("a_to_keep", "=", a_to_keep)
.. runpython::
:showcode:
:store:
a_to_keep = 5
print("a_to_keep", "=", a_to_keep)
.. runpython::
:showcode:
:restore:
a_to_keep += 5
print("a_to_keep", "=", a_to_keep)
.. index:: sphinx-autorun
`sphinx-autorun