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: See sphinx docs for a detailed description

hide/hide_output:

Will hide the corresponding block

name/name_output

Define implicit target name that can be referenced by using ref

caption/caption_output

Will add a caption above the block

linenos/linenos_output

Will add line numbers

lineno-start/lineno-start_output

Set the first line number of the block. Linenos is also automatically activated

emphasize-lines/emphasize-lines_output

Emphasize particular lines of the block

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
1print('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.

Further Examples

This is an example with captions, highlights and name.

.. exec_code::
   :lineno-start: 5
   :emphasize-lines: 1, 4
   :caption: This is an important caption
   :caption_output: This is an important output caption
   :name: my_example_1
   :name_output: my_output_1

   print('My')
   # This is a comment

   print('Output!')

Generated view

This is an important caption
5print('My')
6# This is a comment
7
8print('Output!')
This is an important output caption
My
Output!

Create a link using to the blocks by using the name:

See :ref:`this code snippet <my_example_1>` for an example
See :ref:`this code snippet <my_output_1>` for an example output

See this code snippet for an example See this code snippet for an example output