Using Sphinx to write personal websites and blogs

Question

Sphinx is a Python library to generate nice documentation from a set of ReST formatted text files. I wonder if any one has written Sphinx plugins to make it generate personal websites and blogs. Especially for blogs, there needs to be a way to automatically list posts chronologically and generate a RSS feed. One needs to write a Sphinx plugin to do such special page/xml generation. Has anyone tried this before?

Accepted Answer

I've done it at http://reinout.vanrees.org/weblog. The key trick is to add a preprocessor step. I've got my blog entries in a `weblog/yyyy/mm/dd/` folder structure.

A script iterates through that folder structure, creating `index.txt` files in every directory, listing the sub-items. The normal Sphinx process then renders those `index.txt` files.

I added a custom Sphinx processor for tags. So ".. tags:: python, buildout" somewhere at the top of my weblog entry generates the tags. And the preprocessor again collects those entries and writes out a `weblog/tags/TAGNAME.txt` file which Sphinx again renders normally.

The preprocessor also creates the root `weblog/index.txt` with the latest 10 entries. And an `weblog/atom.xml` in (hardcoded) the output directory for the rss feed.

So: you need some custom stuff, but it is pretty much plain text, so for me it was a nice exercise. And you get to write some helper scripts to make life easy, for instance one that copies a textfile from somewhere to today's weblog directory (including creation of missing directories and an "svn add").

Using Sphinx to write personal websites and blogs

Solution

Problem