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 docs.produce-and-publish.com). 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:

• Sphinx supports the export/generation of the content as JSON (JSON builder aka “make json”).
• The generated JSON documents can be used easily inside my Pyramid application through a tiny traverser dealing with paths and extensions
• The traverser code can be found here: https://github.com/zopyx/zopyx.pyramid.ppdemo/blob/master/ppdemo/views.py

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 https://github.com/zopyx/zopyx.pyramid.ppdemo/blob/master/ppdemo/templates/sphinx.pt).

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