code_include

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-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:

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

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