I’ve worked on a few Sphinx-based websites for software projects lately. (I’ve found the matplotlib sphinx tutorial useful for getting started.) A couple of examples are the PyCogent and PyNAST sites.
One thing I’ve needed to do was integrate a news feed that is easy for developers on the project to update, without having to mess with uploading new html, sharing the site password, etc. The solution I came up with was creating a wordpress blog (e.g., PyCogent, PyNAST); using feed.informer to generate a javascript feed digest; and integrating that javascript into the sidebar via custom layout.html page in Sphinx. See the ‘News and Announcements’ sections on the two sites I mentioned above.
The steps are as follows:
- Create a blog (I chose wordpress, since that’s what I’ve used the most).
- Create a free feed.informer account. There are a few different sites out there that will host your javascript-based ‘feed digest’, but I’ve found this one to be the least obnoxious in terms of including an advertisements (see the ‘Powered by Feed Informer’ note on my sites) and fairly customizable.
- Run through the steps of adding your feed to a digest at feed.informer — for my PyNAST wordpress blog, the feed url is: http://pynast.wordpress.com/pynast.
One option you should be sure to use is ‘Show Only Live Items’, which has the effect of refreshing the feed rather than reading it from feed.informer’s cache. This allows you to, for example, delete posts in your blog and have them no longer show up in your feed digest.
- Paste the provided javascript into your layout.html file in your sphinx project if you’ve created one. If you haven’t created a custom layout.html file, you can work from the PyCogent layout.html or the PyNAST layout.html.
layout.html is the only file you should need to modify to integrate javascript into a Sphinx sidebar. No changes were necessary to conf.py.
- Re-build the html pages, and view the result. I usually end up going through a couple of iterations of steps 3-5 to get the feed digest looking exactly as I want it.
- Post the html.
That should do it. You should now be able to update your blog, and have that automatically update the News and Annonucements section on your website. If other developers on the project need to make updates as well, you can have them create wordpress accounts, and then add them as contributors on the blog. You’ll then have multiple users able to update this without sharing any passwords.
