Previously I generated my tutorial pages (Python Tutorial) by hand writing *.shtml files.  I used Apache SSI (server side includes) as a very basic templating system to construct pages from basic building blocks.  For each code sample I create a *py file.

A makefile ties everything together by running a perl utility, code2html over all the python files to create *.py.html files.  These code snippets are then inserted into the tutorial pages with include directives.

I'm currently in the process of migration to a scheme that uses a real templating system (Genshi) and the Pygments library to build the complete tutorial.  The finished scripts should allow me to work directly with HTML and Python files on disk and compile the whole thing into a complete document.

Reasons for migration:
  • The toolchain will be all python eases migration to Django/Twisted web layer
  • Genshi templates will help ensure that the markup is correct and make it considerably easier to modify the entire tutorials look and feel going forward.  (Or reuse these work for other tutorials I'd like to work on in the future).  
  • Pygments is an excellent syntax highligher with support for a ton of languages.
  • There is still a build step
  • Creating tutorials still involves writing html by hand
  • No web interface to edit pages or create new ones