code-block (pygments, highlight)

See also

Sphinx does syntax highlighting using the Pygments library.

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

.. code-block:: python

Some python code.

You can specify different highlighting for a code block using the following syntax:

Default highlighter

With two colons you start a code block using the default highlighter::

        # Some Python code here
        # The language defaults to Python, we don't need to set it
        if 1 == 2:
                pass

With two colons you start a code block using the default highlighter:

# Some Python code here
# The language defaults to Python, we don't need to set it
if 1 == 2:
    pass

python highlighter

You can specify the language used for syntax highlighting by using code-block:

.. code-block:: python

        if "foo" == "bar":
                # This is Python code
                pass

if "foo" == "bar":
    # This is Python code
    pass

xml highlighter

For example, to specify XML:

.. code-block:: xml

        <somesnippet>Some XML</somesnippet>

<somesnippet>Some XML</somesnippet>

console highlighter

… or UNIX shell:

.. code-block:: console

   # A comment
   sh myscript.sh

# A comment
sh myscript.sh

ini highlighter

… or a buildout.cfg:

.. code-block:: ini

   [some-part]
   # A random part in the buildout
   recipe = collective.recipe.foo
   option = value

[some-part]
# A random part in the buildout
recipe = collective.recipe.foo
option = value

pycon python console highlighter

… or interactive Python:

.. code-block:: pycon

   >>> class Foo:
   ...     bar = 100
   ...
   >>> f = Foo()
   >>> f.bar
   100
   >>> f.bar / 0
   Traceback (most recent call last):
         File "<stdin>", line 1, in <module>
   ZeroDivisionError: integer division or modulo by zero

>>> class Foo:
...     bar = 100
...
>>> f = Foo()
>>> f.bar
100
>>> f.bar / 0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: integer division or modulo by zero

highlighting mode for the whole document

Setting the highlighting mode for the whole document:

.. highlight:: console

All code blocks in this doc use console highlighting by default:

some shell commands

If syntax highlighting is not enabled for your code block, you probably have a syntax error and Pygments will fail silently.

The full list of lexers and associated short names is here: http://pygments.org/docs/lexers/