November 27, 2012

Integrating Sphinx documentation into a Pyramid application

I am currently working on the relaunch of my Produce & Publish product site. I decided to go with Pyramid (instead of Plone) this time since different functionality has to be integrated under one hood. The core application is based on a twitter/bootstrap theme (nothing special so far). I wrote already a bunch of documentation using Sphinx (result hosted on Now the Sphinx site/content should be integrated into the Pyramid application. One option would be using a dedicated twitter/bootstrap theme for Sphinx or using Diazo. I decided against both options. A twitter/bootstrap theme for Sphinx is doable but requires double work (keeping the twitter/bootstrap theme in Sphinx and Pyramid in sync). Using Diazo also was not much appealing...yet another moving part.

The solution I come up with is the following:

Now traversing to /documentation/index will cause Pyramid to traverse into a specific part of the filesystem holding the documentation JSON-ified by Sphinx, picking up the JSON data and rendering it using a tiny template (see

Disclaimer: the code is a proof of concept and more a hack than a final solution...but it works nicely so far...all image are being display and all links are fully working