Template Driven Websites with Sphinx

This week I wanted to find (or write) a tutorial on creating template-driven static web sites for my web students.  Why static?  Well, this semester's class focuses on client-side technologies and design concerns; the students aren't necessarily programmers and we don't have any dynamic hosting space for them.  Many sites don't need +4 on demand page materialization with magic database access; on the other hand, manually maintaining navigation and consistency for more than a couple of pages is tedious in the extreme.

I've used a homebrew script to generate my own site for a while, but I wanted something a little more robust for this assignment.  My mental list of requirements and desired characteristics as I started researching possible options included:

• ability to create a static site with consistent navigation from a set of text sources and a template
• ideally use reStructuredText as the documentation format
• quick and easy startup; complexity and features are fine where they are necessary, but that complexity will obscure assignment learning objectives if it is not carefully designed
• no administrator privileges required

The first few systems I looked at were not very satisfying: several assume you are coming from the dynamic world, many use custom template systems, and none seem to meet all of the requirements I had in mind.  Just before I resigned myself to compromise, though, I remembered Brandon's post on using Sphinx and Mercurial as a CMS.  Sphinx looked promising: it uses reStructuredText as the document format and Jinja for templating; it is a mature project that has been used as the documentation system on many large-scale projects. Could it be used as the template system for my students?

After trying it out, I must say that I am mightily impressed with Sphinx, which met all of my requirements beyond hope.  My first Sphinx project, in true fact despite the seemingly contrived recursion, is an introductory tutorial on creating template driven websites with Sphinx, which I foisted upon my students last night to a generally favorable reception.   Using virtualenv, students can create a self-contained environment that facilitates the installation of Sphinx and its dependencies without requiring administrator rights.  Sphinx, while powerful, provides a quick start utility that eases the creation of a new site and allows students to get started rapidly.  Plus, since Sphinx uses Jinja templates, students gain exposure to a real template engine that should facilitate the transition to server-side application development next semester.

•  Tutorial: Template Driven Websites with Sphinx
•  Source code and issue tracker on bitbucket