Usage

Without options

.. exec_code::

   print('Easy!')

Generated view

print('Easy!')

Easy!

Options

It’s possible to further configure both the code block and the output block with the following options:

hide_code/hide_output:: Will hide the corresponding block
caption/caption_output: Will add a caption above the block
linenos/linenos_output: Will add line numbers
language/language_output:: Will add syntax highlighting for the specified language

The default for the code block is python, the default for the output block is plain text

Example:

.. exec_code::
   :linenos:
   :hide_output:
   :caption: This is an important caption

   print('Easy!')

Generated view

This is an important caption

print('Easy!')

Code from files

It’s possible to have code in example files with the filename option. The folder that is used to resolve to a file name can be configured.

Example:

.. exec_code::
   :filename: file_example.py

Generated view

print('This is code from an example file')

This is code from an example file

Code Markers

It’s possible to hide parts of the code (e.g. to setup a working example) and it’s possible to skip part of the code execution. This is possible with the #hide:[start|stop|toggle] or #skip:[start|stop|toggle] marker in the code. Empty lines after a disabling marker will be ignored.

Spaces and dashes are ignored for the case insensitive marker detection so these are all the same:

#HIDE:START
# hide: start
# ----- hide: start -----
     # ----- hide: start -----

Hiding code parts

.. exec_code::

   # --- hide: start ---
   print('Setup!')
   #hide:toggle

   print('Easy!')

   # --- hide: start ---
   print('Hidden!')
   # --- hide: stop ---

   # Note the missing entries!
   print('Visible!')

Generated view (note the skipped empty lines after the stop and disabling toggle marker)

print('Easy!')

# Note the missing entries!
print('Visible!')

Setup!
Easy!
Hidden!
Visible!

Skipping code parts

.. exec_code::

   # --- skip: start ---
   print(f'1 / 0 = {1 / 0}')
   # --- skip: stop ---

   # --- hide: start ---
   print('1 / 0 = 0')
   # --- hide: stop ---

Generated view

print(f'1 / 0 = {1 / 0}')

1 / 0 = 0

With the combination of skip and hide it’s possible to “simulate” every code.