How to combine ReST and Pygments

Many Python people use ReST for documentation their sourcecode, programs, scripts et cetera.But as the description at Using Pygments in ReST documents you need copy external/rst-directive.py to your code. It's not enough detail.

let me give you an example:

1. Get it from the Cheese Shop.
2. unzip the file and then open the external/rst-directive.py with your favorite text editor.
3. edit the file under the //Lib/site-packages/docutils/parsers/rst/__init__.py
4. add following code to the bottom of the file and save it.
5. now you can generate the rest documnet with source code highlight.

Here is an example that I used:

# 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)

# Add name -> formatter pairs for every variant you want to use
VARIANTS = {
   'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),    
  
}


from docutils import nodes
from docutils.parsers.rst import directives

from pygments import highlight
from pygments.lexers import get_lexer_by_name, TextLexer

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 = TextLexer()
   # take an arbitrary option if more than one is given
   formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
   parsed = highlight(u'\n'.join(content), lexer, formatter)
   return [nodes.raw('', parsed, format='html')]

pygments_directive.arguments = (1, 0, 1)
pygments_directive.content = 1
pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])

directives.register_directive('sourcecode', pygments_directive)