Bringing Twitter Bootstrap to Sphinx
Bootstrap is an open source CSS/JS framework from the folks at Twitter that provides base typography, layout (grids), forms / form inputs, tables and navigation, and has been gaining wide popularity among developers. In my personal experience with a couple of sites and projects, Bootstrap really provides a great starting point for a frontend that provides good extensibility over time.
Sphinx is the most popular Python documentation generator tool. It has fantastic Python module docstring / comment parsing in addition to a sensible static pages framework, providing a great final web site built from both inline code documentation and outside web pages.
In the process of starting up a number of new Sphinx projects, I decided that I would really like to use Bootstrap as the underlying UI framework. Fortunately, Sphinx supports custom theme plugins, so I spent a couple of days hacking, and created a Sphinx Bootstrap Theme, which is now available on GitHub.
[![Sphinx Bootstrap Theme Demo][img_sbt_teaser_th]][img_sbt_teaser] [img_sbt_teaser_th]: http://loose-bits.com/media/img/2011/12/09/sbt_teaser_thumb.png [img_sbt_teaser]: http://loose-bits.com/media/img/2011/12/09/sbt_teaser.png
Sphinx themes can be installed either as a directory of files or a zip file. For simplicity’s sake, we’ll go with a pre-packaged zip file installation here.
First, set up a themes directory, which typically is something like “_themes” located in your Sphinx source directory:
$ cd /path/to/source $ mkdir -p _themes
$ cd /path/to/source/_themes $ wget https://github.com/downloads/ryan-roemer/sphinx-bootstrap-theme/bootstrap.zip
As an alternative, you can just clone the theme repository, and place the “bootstrap” directory in your themes directory. The “bootstrap.zip” file should be the most up-to-date version, but getting the directory from source will remain the authoritative current version.
Finally, add the themes directory path and theme name to your source Sphinx “conf.py” file:
# Activate the theme. sys.path.append(os.path.abspath('_themes')) html_theme_path = ['_themes'] html_theme = 'bootstrap' # Optional. Use a shorter name to conserve nav. bar space. html_short_title = 'Demo'
Rebuild your Sphinx documentation, and you should now have the Bootstrap theme up and running! See the README for more information on customizing and hacking on the theme.
The Bootstrap Sphinx theme basically rolls up the site-wide / page-level table of contents, page navigation, and search form into the main navigation top bar.
The first dropdown tab is the “Site” button (expanded and highlighted below).
Internally this wraps up the
globaltoc template using the
[![Site Navigation][img_sbt_nav_site_th]][img_sbt_nav_site] [img_sbt_nav_site_th]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_site_thumb.png [img_sbt_nav_site]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_site.png
The second dropdown tab is the “Page” navigation for table of contents link
within a single page. This wraps the
localtoc template using the
[![Page Navigation][img_sbt_nav_page_th]][img_sbt_nav_page] [img_sbt_nav_page_th]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_page_thumb.png [img_sbt_nav_page]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_page.png
The right “Search” box in the navigation top bar connects to the built-in, client-side search that Sphinx provides. Here we search for the term “bootstrap”:
[![Search Navigation][img_sbt_nav_search_th]][img_sbt_nav_search] [img_sbt_nav_search_th]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_search_thumb.png [img_sbt_nav_search]: http://loose-bits.com/media/img/2011/12/09/sbt_nav_search.png
… which gives us the following page matches:
[![Search Results][img_sbt_search_th]][img_sbt_search] [img_sbt_search_th]: http://loose-bits.com/media/img/2011/12/09/sbt_search_thumb.png [img_sbt_search]: http://loose-bits.com/media/img/2011/12/09/sbt_search.png
The Bootstrap Theme provides an easy means for Twitter Bootstrap integration for my current Sphinx sites. But, as I’ve just put together the theme this week, it is probably still rough around the edges. Any issue reports, pull requests, and feedback are most welcome.