deffbeff

Using Pygments with docutils

Pygments has a very short tutorial for integrating itself with docutils here: http://pygments.org/docs/rstdirective/. However, that was not enough info to get me started using Pygments with rst2html.py. Here are the missing steps:

1. Copy the Pygments supplied rst-directive.py to your docutils installation. Something like:

   cp Pygments/external/rst-directive.py \
    .../site-packages/docutils/parsers/rst/directives/rst_directive.py

   Notice that rst-directive.py became rst_directive.py (dash changed to underscore).

2. Modify rst_directive.py in the docutils directives directory to set INLINESTYLES = True and add a style option to the formatter. Something like:

   # Set to True if you want inline CSS styles instead of classes
   INLINESTYLES = True
   
   from pygments.formatters import HtmlFormatter
   
   # The default formatter
   DEFAULT = HtmlFormatter(noclasses=INLINESTYLES, style='trac')

3. Modify rst2html.py to import the Pygments directive. I added the following line:

   from docutils.parsers.rst.directives import rst_directive

That’s it. Now I can use the ..sourcecode directive in my rst documents. For example:

.. sourcecode:: c++
	int
	main(int argc, char *argv[])
	{
	}