code-block#

Code examples blocks with code-block offers much more options that plain literal-block. It allows syntax highlighting, line numbering, emphasis particular lines and using captions.

Basic usage#

Basic usage of code-block is as simple as:

1.. code-block::
2
3   i = 256 + 256
4   print('The value of i is', i)

i = 256 + 256
print('The value of i is', i)

Syntax highlighting#

Set language to highlight as the directive argument, i.e. .. code-block:: language.

1.. code-block:: python3
2
3   i = 256 + 256
4   print('The value of i is', i)

i = 256 + 256
print('The value of i is', i)

Syntax highlighting uses library Pygments. Pygments calls supported highlight languages as lexers and it has a lexer for almost any language you might imagine - just use python (Python 2), python3, java, javascript, c++, html, json, … as a code-block argument.

tip:: If you don’t want any highlighting, use none or text.

See Pygments’s available lexers page for exhaustive reference. Argument for code-block is one of “short names” (the look of webpage at the time of writing):

../_images/pygments-lexers-webpage.png

Line numbering#

code-block example can be automatically line numbered by :linenos: option.

1.. code-block::
2   :linenos:
3
4   i = 256 + 256
5   print('The value of i is', i)

1i = 256 + 256
2print('The value of i is', i)

Emphasising lines#

With :emphasize-lines: you can highlight one or more lines.

Important

Only non-empty lines are counted. For example, the following snippet we want to actually highlight line 8, but skipping two empty lines it is :emphasize-lines: 6.

 1.. code-block::
 2   :emphasize-lines: 6
 3
 4   $ make gettext
 5
 6   $ cd _build/gettext
 7
 8   $ ls
 9   calling.pot
10   configuration.pot
11   constdata.pot
12   glossary.pot
13   index.pot
14   ...

$ make gettext

$ cd _build/gettext

$ ls
calling.pot
configuration.pot
constdata.pot
glossary.pot
index.pot
...

Captions#

If you write more formal documentation, maybe you look for examples with :caption: caption option.

Caption may contain formatting with any inline element.

After the caption, an anchor will be displayed. Users can copy direct URL to the example (“permalink”).

1.. code-block::
2   :caption: The ``print()`` function.
3
4   i = 256 + 256
5   print('The value of i is', i)
The print() function.#
i = 256 + 256
print('The value of i is', i)

Complex example#

You can combine all possibilities together, indeed.

1.. code-block:: python3
2   :caption: The ``print()`` function.
3   :emphasize-lines: 2
4   :linenos:
5
6   i = 256 + 256
7   print('The value of i is', i)
The print() function.#
1i = 256 + 256
2print('The value of i is', i)

Common issues#

Always specify highlight language#

Code-block highlight even if you don’t specify a language. It is not “autodetect” or “none” (plain text) as you might expect.

.. code-block::

   Nobody knows what highlight language will be used.

Usually default highlight mode for Sphinx is python3. It’s better to always specify language with every code-block or turn off syntax highlighting in conf.py with:

highlight_language = 'none'

See more at Techwriter at work blog.