Options

This page explains some of the available options. There aren’t many at this point in time; if you’d like a feature please open an issue.

Caching

By default, outputs are cached, unless context preservation has been requested in any part of the same document. To turn this off on a per-codeblock basis (e.g. if the code depends on the time which it is run at), specify a falsy value for the :cache: option. For example, what you’ll see in the stdout block here is the last time the documentation was built.

rst
.. exec::
   :cache: false

   from datetime import datetime
   print(datetime.now())


from datetime import datetime
print(datetime.now())

2023-02-21 02:16:16.940128

Context preservation

The :context: option can be used to preserve variables between Python code blocks in the same file. This has no effect on other languages, and is incompatible with caching.

For example, you can define a variable in the first code block:

rst
.. exec::
   :context: true

   x = 5
   print(f'x is equal to {x}')


x = 5
print(f'x is equal to {x}')

x is equal to 5

You can later print the value of x again:

rst
.. exec::

   print(x)


print(x)

5

Note that these variables are cleared upon encountering any code block where the context option is not explicitly enabled. So, if we were to try to print x again at this point, it would fail.

Interspersed text

The :intertext: option may be used to insert text between the code and stdout blocks. Basic RST syntax can be used.

rst
This code

.. exec::
   :intertext: prints the value of the variable ``x``:

   x = 5
   print(x)

This code

x = 5
print(x)

prints the value of the variable x:

5