Documentation

Using Pygments in ReST documents

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!

gavenkoa@gmail.com wrote on Dec. 26, 2012:

My typo: ".. code:: xml" is correct (two colons)...

gavenkoa@gmail.com wrote on Dec. 26, 2012:

I have been frustrating how to enable code highlighting in my rst S5 presentation. Just install Pygments and generate CSS by "pygmentize -S default -f html"!

Next time instead of "::" use ".. code: xml" or ".. code: python".

And you must have rst version >= 9.x.

You needn't integrate rst-directive.py to /bin/rst2s5 or another place.

Jak Wings wrote on Dec. 23, 2012:

Just goto https://bitbucket.org/birkenfeld/pygments-main/src and view the content of external/rst-directive.py
copy the code below "# Options" to rst2html.py before "publish_cmdline..."

schettino72 wrote on March 14, 2010:

I took sometime to figure out that I needed to change this config:

# Set to True if you want inline CSS styles instead of classes
INLINESTYLES = True

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 ?