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?
Answers:
Not Sphinx, but several of the sites at http://codespeak.net/ are done with scripts that take ReST text, generates HTML and uploads them to the site. I didn’t write those scripts though, but I’ve used them.
It’s a reasonable way to generate sites if the sites need to contain a lot of ReST files anyway, like when generating documentation for python modules, which of course these sites are all about. It’s also good if you need the site to be version controlled, because you can keep the source code in svn or hg, or something.
But if you start writing a lot of automatic menues and other extensions, what you will end up with in the end is a content management system. And there is plenty of those around already, so you might want to look at them first.
Another example is the new packages.python.org. There you can generate your documentation in anyway you want it, and then through PyPI upload a zip-file with the docs. Distribute has done this with Sphinx: http://packages.python.org/distribute . But there no particular script is needed, that’s just generating HTML from Sphinx documentation.
However…
I must say that I find the idea of writing a blogging software as Sphinx extension a bit funny, especially since there is so much excellent blogging software out there already. And nothing is going to beat WordPress anyway, and wordpress.com has been a great blogging experience for me. But as an exercise in how much you can abuse Sphinx, why not! 🙂
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:
I redid my personal website (http://homepage.mac.com/s_lott/steve/) in Sphinx. It works nicely. Sadly, the SO markup mangles the _ in my URL.
I also rewrote the entire Introduction to Programming for Non-Programmers (http://homepage.mac.com/s_lott/books/nonprog/html/index.html) book in Sphinx. I’m in the process of rewriting Introduction to Python in Sphinx.
I do not use Sphinx for blogs — it’s not perfectly convenient, but it would work. I use blogspot for low-graphics/high-text and relatively high-velocity blogging. I use iWeb (http://web.me.com/s_lott/Travel/Welcome.html) for high graphic and relatively low-velocity blogging.
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”).
It’s worth knowing that there is an RSS extension for sphinx in the sphinx-contrib extensions, called sphinxcontrib.feed
It and many other fun Sphinx things live at http://bitbucket.org/birkenfeld/sphinx-contrib/
(Disclaimer: I wrote the feed extension.)
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
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.
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.
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?
Not Sphinx, but several of the sites at http://codespeak.net/ are done with scripts that take ReST text, generates HTML and uploads them to the site. I didn’t write those scripts though, but I’ve used them.
It’s a reasonable way to generate sites if the sites need to contain a lot of ReST files anyway, like when generating documentation for python modules, which of course these sites are all about. It’s also good if you need the site to be version controlled, because you can keep the source code in svn or hg, or something.
But if you start writing a lot of automatic menues and other extensions, what you will end up with in the end is a content management system. And there is plenty of those around already, so you might want to look at them first.
Another example is the new packages.python.org. There you can generate your documentation in anyway you want it, and then through PyPI upload a zip-file with the docs. Distribute has done this with Sphinx: http://packages.python.org/distribute . But there no particular script is needed, that’s just generating HTML from Sphinx documentation.
However…
I must say that I find the idea of writing a blogging software as Sphinx extension a bit funny, especially since there is so much excellent blogging software out there already. And nothing is going to beat WordPress anyway, and wordpress.com has been a great blogging experience for me. But as an exercise in how much you can abuse Sphinx, why not! 🙂
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:
I redid my personal website (http://homepage.mac.com/s_lott/steve/) in Sphinx. It works nicely. Sadly, the SO markup mangles the _ in my URL.
I also rewrote the entire Introduction to Programming for Non-Programmers (http://homepage.mac.com/s_lott/books/nonprog/html/index.html) book in Sphinx. I’m in the process of rewriting Introduction to Python in Sphinx.
I do not use Sphinx for blogs — it’s not perfectly convenient, but it would work. I use blogspot for low-graphics/high-text and relatively high-velocity blogging. I use iWeb (http://web.me.com/s_lott/Travel/Welcome.html) for high graphic and relatively low-velocity blogging.
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”).
It’s worth knowing that there is an RSS extension for sphinx in the sphinx-contrib extensions, called sphinxcontrib.feed
It and many other fun Sphinx things live at http://bitbucket.org/birkenfeld/sphinx-contrib/
(Disclaimer: I wrote the feed extension.)
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
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.
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.