Documentation

Using Pygments in ReST documents

back to documentation 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.

From Pygments 0.9, the directive is shipped in the distribution as external/rst-directive.py. You can copy and adapt this code to your liking.

Did you like the documentation? Do you have suggestions? Leave your comment here!

Georg wrote on March 2, 2008:

re your second question: the handlecodeblocks option does not refer to this directive at all, but to the Pygments reST lexer. I've removed that paragraph now -- it's too confusing.

Georg wrote on March 2, 2008:

You have to copy the external/rst-directive.py file from the Pygments distribution in your code, possibly adapting it, and then import the module from your docutils-using application.

Marcin.Kasperski@acn.waw.pl wrote on March 1, 2008:

Well, I am next one who came here because I want to use .. sourcecode:: and have no clue how to do it.... I just easy_install-ed newest pygments and docutils and still the directive is not recognized.

In particular I have no clue where should I put this handlecodeblocks option - it it possible to use it with rst2html somehow?

Georg wrote on Dec. 2, 2007:

Thanks, the file is now fixed.

nsteinmetz@gmail.com wrote on Nov. 18, 2007:

Ok, I get if from the content of the rst-directives.py - and btw, headings of the file talks about MoinMoin - a copy/paste issue I guess ;-)

nsteinmetz@gmail.com wrote on Nov. 18, 2007:

Hello,

New to pygments, I do not get the ..sourcecode:: and .. code:: with the handlecodeblocs option. Could you provide an exemple please ?

 

Note: comments may be edited or deleted if they are of an offensive or inappropriate nature.