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?

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

Solution 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

Solution 3

Doug hellmann, author of the 'Python Module of the Week' does his site using Sphinx.

http://www.doughellmann.com/PyMOTW/

He has several posts which cover sphinx topics that can probably help you on your way:

http://blog.doughellmann.com

Solution 4

If you need to write in reStructuredText , you should try Pelican.

Pelican is a static site generator, written in Python. You'll be able to write your blog entries directly in reStructuredText or Markdown.

Solution 5

Check out ABlog for Sphinx

I am in the process of starting a blog myself using it.

I stumbled across it while I was going through my feeds in feedly. I searched about it and found it interesting. It also has Disqus integration, and can generat Atom feeds (not very sure what that is at the moment, I am new to the web)

I have not yet figured out how to deploy my test blog, will update when i find out something.

View more solutions

Comments

[Sridhar Ratnakumar]

The first two links are broken!

[user1066101]

Silly SO markup mangles the _'s. I think I have them fixed. The point is that I use Sphinx heavily.

[Roberto Bonvallet]

Using Sphinx over Wordpress has the advantage that your articles are just plain text, which can be written in your favorite editor, put under version control, can be grepped, syntax-highlighted, etc.

[Sakie]

And Wordpress code highlighting is terrible for python, in my experience, whereas in Sphinx, it works :)

[Chris Johnson]

Can you sure your tag solution?

[user2740101]

@ChrisJohnson: yes, see reinout.vanrees.org/weblog/2012/01/22/… . Custom made and partially hardcoded. Feel free to copy/paste. I might clean it up into a library one day, but I've been thinking that for two years now, so I'm not making a fixed promise right now :-)

[Jan Doggen]

I have edited your question bacuse the way it was written smelled like spam. Maybe you can edit it further and explain why it would be a good solution for the OP? Does it e.g. generate RSS as he/she asked? Just a link is not enough.

[ostrokach]

hmm, ABlog is actually the best answer. Compared to tinkerer, It is more actively maintained and allows posts to be tagged using rst rather then relying on folder hierarchy. It supports RSS feeds, font awesome, Disqus and many other features.