Pygments enhanced docutils front-ends

The example code in "Using Pygments in ReST documents" defines a new "sourcecode" directive. The directive takes one argument language and uses the Pygments source highlighter to parse and render its content as a colourful source code block.

Combining the pygments example code with the standard docutils front-ends, results in front-end scripts generating output documents with syntax colour. For consistency with the majority of existing add-ons, the directive is renamed to "code-block".

rst2html-pygments

enhances the standard docutils rst2html front-end to generate a HTML rendering with syntax highlight.

rst2latex-pygments

enhances docutils' rst2latex to generate LaTeX with syntax highlight.

Advantages:

• Easy implementation with no changes to the stock docutils.
• Separation of code blocks and ordinary literal blocks.

Disadvantages:

• "code-block" content is formatted by pygments and inserted in the document tree as a "raw" node making the approach writer-dependant.
• documents are incompatible with the standard docutils because of the locally defined directive.
• more "invasive" markup distracting from content
• no "minimal" code block marker -- three additional lines per code block

The disadvantages lead to the alternative implementation with the demonstrator front ends rst2html-highlight and rst2latex-highlight.