Previous topic

Next topic

This Page

Quick search

Examples of Python source code or interactive sessions are represented using
standard reST literal blocks. They are started by a :: at the end of the
preceding paragraph and delimited by indentation.

Representing an interactive session requires including the prompts and output
along with the Python code. No special markup is required for interactive
sessions. After the last line of input or output presented, there should not be
an “unused” primary prompt; this is an example of what not to do:

>>> 1 + 1
2
>>>

Syntax highlighting is done with Pygments (if it’s
installed) and handled in a smart way:

There is a “highlighting language” for each source file. Per default, this is
'python' as the majority of files will have to highlight Python snippets,
but the doc-wide default can be set with the highlight_language
config value.

Within Python highlighting mode, interactive sessions are recognized
automatically and highlighted appropriately. Normal Python code is only
highlighted if it is parseable (so you can use Python as the default, but
interspersed snippets of shell commands or other code blocks will not be
highlighted as Python).

The highlighting language can be changed using the highlight directive,
used as follows:

..highlight:: c

This language is used until the next highlight directive is encountered.

For documents that have to show snippets in different languages, there’s also
a code-block directive that is given the highlighting language
directly:

If installed, Pygments can generate line numbers for code blocks. For
automatically-highlighted blocks (those started by ::), line numbers must be
switched on in a highlight directive, with the linenothreshold
option:

..highlight:: python
:linenothreshold:5

This will produce line numbers for all code blocks longer than five lines.

For code-block blocks, a linenos flag option can be given to switch
on line numbers for the individual block:

..code-block:: ruby
:linenos:
Some more Ruby code.

Additionally, an emphasize-lines option can be given to have Pygments
emphasize particular lines:

Longer displays of verbatim text may be included by storing the example text in
an external file containing only plain text. The file may be included using the
literalinclude directive. [1] For example, to include the Python source file
example.py, use:

..literalinclude:: example.py

The file name is usually relative to the current file’s path. However, if it
is absolute (starting with /), it is relative to the top source
directory.

Tabs in the input are expanded if you give a tab-width option with the
desired tab width.

The directive also supports the linenos flag option to switch on line
numbers, the emphasize-lines option to emphasize particular lines, and
a language option to select a language different from the current
file’s standard language. Example with options:

Include files are assumed to be encoded in the source_encoding.
If the file has a different encoding, you can specify it with the
encoding option:

..literalinclude:: example.py
:encoding:latin-1

The directive also supports including only parts of the file. If it is a
Python module, you can select a class, function or method to include using
the pyobject option:

..literalinclude:: example.py
:pyobject:Timer.start

This would only include the code lines belonging to the start() method in
the Timer class within the file.

Alternately, you can specify exactly which lines to include by giving a
lines option:

..literalinclude:: example.py
:lines:1,3,5-10,20-

This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.

Another way to control which part of the file is included is to use the
start-after and end-before options (or only one of them). If
start-after is given as a string option, only lines that follow the first
line containing that string are included. If end-before is given as a
string option, only lines that precede the first lines containing that string
are included.

You can prepend and/or append a line to the included code, using the
prepend and append option, respectively. This is useful e.g. for
highlighting PHP code that doesn’t include the <?php/?> markers.

New in version 0.4.3: The encoding option.

New in version 0.6: The pyobject, lines, start-after and end-before options,
as well as support for absolute filenames.

New in version 1.0: The prepend and append options, as well as tab-width.