reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

Table of Contents

Intro

Collections

Elements

Etc.

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.

Previous: caution | Next: contents

On this page