Some of you regulars out there may have noticed an interesting change in the
presentation of some of my articles: source code highlighting. I've been
interested in doing this for quite some time, I just never really got around to
implementing it until last night.
I found this implementation process to be a bit more complicatd than I had
anticipated. For my own benefit as well as for anyone else who wants to do the
same thing, I thought I'd document my findings in a thorough article for how to
add syntax highlighting to an existing Django- and reStructuredText-powered Web
site.
The power behind the syntax highlighting is:
Python is a huge player in this feature because reStructuredText (ReST) was
built for Python, Pygments is the source highlighter (written in Python), and
Django is written in Python (and my site is powered by Django). Some of you
may recall that I converted all of my articles to ReST not too long ago because
it suited my needs better than Textile, my previous markup processor. At the
time, I was not aware that the conversion to ReST would make it all the easier
for me to implement the syntax highlighting, but last night I figured out that
that conversion probably saved me a lot of frustration. Cascading Stylesheets
(CSS) are responsible for making the source code actually look good, while
Pygments takes care of assigning classes to various parts of the designated
source code and generating the CSS.
So, the first set of requirements, which I will not document in this article,
are that you already have a Django site up and running and that you're familiar
with ReST syntax. If you have
the django.contrib.flatpages application installed already, you can type up
some ReST documents there and apply the concepts discussed in this article.
Next, you should ensure that you have Pygments installed. There are a variety
of ways to install this. Perhaps the easiest and most platform-independent
method is to use easy_install:
$ easy_install pygments
This command should work essentially the same on Windows, Linux, and Macintosh
computers. If you don't have it installed, you can get it from its website. If you're using a
Debian-based distribution of Linux, such as Ubuntu, you could do something like
this:
$ sudo apt-get install python-pygments
...and it should take care of downloading and installing Pygments.
Alternatively, you can download it straight from the PyPI page and install it manually.
Now we need to install the Pygments ReST directive. A ReST directive is
basically like a special command to the ReST processor. I think this part was
the most difficult aspect of the implementation, simply because I didn't know
where to find the Pygments directive or how to write my own. Eventually, I
ended up downloading the Pygments-1.0.tar.gz file from PyPI, opening the
Pygments-1.0/external/rst-directive.py file from the archive, and copying
the stuff in there into a new file within my site.
For my own purposes, I made some small adjustments to the directive over what
come with the Pygments distribution. I think it would save us all a lot of
hassle if I just copied and pasted the directive, as I currently have it, so
you can see it first-hand.
|
"""
The Pygments reStructuredText directive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This fragment is a Docutils_ 0.4 directive that renders source code
(to HTML only, currently) via Pygments.
To use it, adjust the options below and copy the code into a module
that you import on initialization. The code then automatically
registers a ``code-block`` directive that you can use instead of
normal code blocks like this::
.. code:: python
My code goes here.
If you want to have different code styles, e.g. one with line numbers
and one without, add formatters with their names in the VARIANTS dict
below. You can invoke them instead of the DEFAULT one by using a
directive option::
.. code:: python
:number-lines:
My code goes here.
Look at the `directive documentation`_ to get all the gory details.
.. _Docutils: http://docutils.sf.net/
.. _directive documentation:
http://docutils.sourceforge.net/docs/howto/rst-directives.html
:copyright: 2007 by Georg Brandl.
:license: BSD, see LICENSE for more details.
"""
# Options
# ~~~~~~~
# Set to True if you want inline CSS styles instead of classes
INLINESTYLES = False
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)
parsed = '<div class="codeblock">%s</div>' % parsed
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('code-block', pygments_directive)
|
I won't explain what that code means, because, quite frankly, I'm still a
little hazy on the inner workings of ReST directives myself. Suffice it to say
that this snippet allows you to easily highlight blocks of code on ReST-powered
pages.
The question now is: where do I put this snippet? As far as I'm aware, this
code can be located anywhere so long as it is loaded at one point or another
before you start your ReST processing. For the sake of simplicity, I just
stuffed it in the __init__.py file of my Django site. This is the
__init__.py file that lives in the same directory as manage.py and
settings.py. Putting it in that file just makes sure it's loaded each time
you start your Django site.
To make Pygments highlight a block of code, all you need to do is something
like this:
.. code:: python
print 'Hello world!'
...which would look like...
print 'Hello world!'
If you have a longer block of code and would like line numbers, use the
:number-lines: option:
.. code:: python
:number-lines:
for i in range(100):
print i
...which should look like this...
|
for i in range(100):
print i
|
That's all fine and dandy, but it probably doesn't look like the code is
highlighted at all just yet (on your site, not mine). It's just been marked up
by Pygments to have some pretty CSS styles applied to it. But how do you know
which styles mean what?
Luckily enough, Pygments takes care of generating the CSS files for you as
well. There are several attractive styles that come with Pygments. I would
recommend going to the Pygments demo to see
which one suits you best. You can also roll your own styles, but I haven't
braved that yet so I'll leave that for another day.
Once you choose a style (I chose native for Code Koala), you can run the
following commands:
$ pygmentize -S native -f html > native.css
$ cp native.css /path/to/site/media/css
(obviously, you'd want to replace native with the name of the style you
like the most) Finally, add a line to your HTML templates to load the newly
created CSS file. In my case, it's something like this:
<link rel="stylesheet" type="text/css" href="/static/styles/native.css" />
Now you should be able to see nicely-formatted source code on your Web pages
(assuming you've already got ReST processing your content).
If you haven't been using ReST to generate nicely-formatted pages, you should
make sure a couple of things are in place. First, you must have the
django.contrib.markup application installed. Second, your templates should
be setup to process ReST markup into HTML. Here's a sample
templates/flatpages/default.html:
|
{% extends 'base.html' %}
{% load markup %}
{% block title %}{{ flatpage.title }}{% endblock %}
{% block content %}
<h2>{{ flatpage.title }}</h2>
{{ flatpage.content|restructuredtext }}
{% endblock %}
|
So that short template should allow you to use ReST markup for your flatpages,
and it should also take care of the magic behind the .. code:: python
directive.
I should also note that Pygments can handle a TON of languages. Check out
the Pygments demo for a list of languages it knows how to highlight.
I think that about does it. Hopefully this article will help some other poor
chap who is currently in the same situation as I was last night, and hopefully
it will save you a lot more time than it took me to figure out all this junk.
If it looks like I've missed something, or maybe that something needs further
clarification, please comment and I'll see what I can do.