Pygments

Using Pygments in ReST documents

« Back To Index

Many Python people use ReST for documentation their sourcecode, programs, scripts et cetera. This also means that documentation often includes sourcecode samples or snippets.

You can easily enable Pygments support for your ReST texts using a custom directive -- this is also how this documentation displays source code.

Add this code to the script you use for building the HTML documentation:

from docutils import nodes
from docutils.parsers.rst import directives
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter

pygments_formatter = HtmlFormatter()

def pygments_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    try:
        lexer = get_lexer_by_name(arguments[0])
    except ValueError:
        # no lexer found - use the text one instead of an exception
        lexer = get_lexer_by_name('text')
    parsed = highlight(u'\n'.join(content), lexer, pygments_formatter)
    return [nodes.raw('', parsed, format='html')]
pygments_directive.arguments = (1, 0, 1)
pygments_directive.content = 1
directives.register_directive('sourcecode', pygments_directive)

Now you should be able to use Pygments to highlight source code in your ReST files using this syntax:

.. sourcecode:: language

    your code here