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?

Answer 1

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").

Answer 2

As of now (February, 2012), there are different resources available to do what you want:

A blog engine based on sphinx: http://tinkerer.me/

Reinout Van Rees' blog: https://github.com/reinout/reinout.vanrees.org

The feed contrib extension: https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/feed/README