Include Pygments highlighted code with reStructuredText
=======================================================

:author: Colin Dunklau

Use this plugin to make writing coding tutorials easier! You can
maintain the example source files separately from the actual article.

Based heavily on ``docutils.parsers.rst.directives.Include``. Include
a file and output as a code block formatted with pelican's Pygments
directive.

Note that this is broken with the Docutils 0.10 release, there's a
circular import. It was fixed in trunk:
http://sourceforge.net/p/docutils/bugs/214/

Directives
----------

.. code:: rst

    .. code-include:: incfile.py
        :lexer: string, name of the Pygments lexer to use, default 'text'
        :encoding: string, encoding with which to open the file
        :tab-width: integer, hard tabs are replaced with `tab-width` spaces
        :start-line: integer, starting line to begin reading include file
        :end-line: integer, last line from include file to display

``start-line``, and ``end-line`` have the same meaning as in the
docutils ``include`` directive, that is, they index from zero.

Example
-------

./incfile.py:

.. code:: python

    # These two comment lines will not
    # be included in the output
    import random

    insults = ['I fart in your general direction',
               'your mother was a hampster',
               'your father smelt of elderberries']

    def insult():
        print random.choice(insults)
    # This comment line will be included
    # ...but this one won't

./yourfile.rst:

.. code:: rst

    How to Insult the English
    =========================

    :author: Pierre Devereaux

    A function to help insult those silly English knnnnnnniggets:

    .. code-include:: incfile.py
        :lexer: python
        :encoding: utf-8
        :tab-width: 4
        :start-line: 3
        :end-line: 11