Sphinx Bootstrap Theme Updates!

Almost a year ago, I created the Sphinx Bootstrap Theme project to bring together two of my favorite open source technologies - Sphinx and Twitter Bootstrap. Sphinx is a widely-used Python-based authoring tool for creating static websites and API documentation. Twitter Bootstrap is a frontend JavaScript / CSS framework that offers a consistent UI experience, typography, grid systems, navigation / button / other components, and responsive features for mobile design.

Since its introduction, I now use Sphinx with the Bootstrap Theme for my open source Python projects and we use the theme for all internal technical documentation at work. Coming up on the project’s anniversary, it seemed appropriate to add some tweaks and enhancements to increase the usability and extensibility of the theme.

Improvements now available in version 0.1.0 include:

• Upgraded the Bootstrap libraries to version 2.2.1.
• Added new theme options to control UI appearance and behavior.
• Navigation bar menus now have hierarchical sub-menus for a more intuitive experience.
• Reworked the underlying layout code to support fully responsive design, allowing any site to look great on mobile devices like an iPhone or iPad.
• Created a PyPI package to permit installation via pip install sphinx_bootstrap_theme.

So let’s see how everything looks and works with the new v0.1.0 theme.

Theme Options

The theme has several new options that you can set in the “conf.py” configuration file.

Bootstrap Theme Demo Site

Let’s start with the Bootstrap Theme’s own demonstration website.

[![Sphinx Bootstrap Theme Desktop View][img_sbt_desk]][img_sbt_desk] [img_sbt_desk]: http://loose-bits.com/media/img/2012/11/19/sbt_desk.png

AMD/RequireJS

The Asynchronous Module Definition (AMD) provides a framework for predictable loading of JavaScript modules and dependencies. AMD is an extension of (and possible transport for) the CommonJS specification.

The RequireJS library implements AMD with loading, bundling and other functionality. It brings sensible imports (with define and require) to frontend JavaScript, instead of the usual array of script includes into the global namespace. Interestingly, as Node.js implements CommonJS-style require’s, there are also support modules to bring Node.js code under AMD.

Take both of things together and we have the real potential for shared JavaScript code across the browser and server. As we use this exact approach at work for our new Backbone.js frontend / Express Node.js backend web application, I created a short talk that I presented at the November 11, 2012 Node.DC meetup, entitled “Shared Code with AMD/RequireJS”.

![AMD/RequireJS Talk][img_talk] [img_talk]: http://loose-bits.com/media/img/2012/11/15/nodedc-requirejs.png

Deck.js Starter

Deck.js is a modern presentation framework for creating interactive HTML-based interactive slide decks. The framework provides:

• A basic boilerplate.
• CSS themes.
• Extensions including a menu, “go to” button, transitions, etc.

To create a presentation, simply edit the HTML files and host a static website and you have an auto-magic slide deck, available to the world.

I have now done a couple of deck.js-based presentations, and find it incredibly useful, but noticed I was re-implementing the same scaffolding enhancements. I wrapped up these common enhancements in a GitHub project, Deck.js Starter. The notable enhancements the starter kit has are:

• Jade templates with Markdown support for faster slide authoring.
• Executable JavaScript code snippets using CodeMirror.
• Executable CoffeeScript code snippets via some specific tweaks I made to the CodeMirror deck.js extension.

Essentially, you can download and install the starter kit, and just start authoring new slides. The starting deck provides a short demo and is available at:

![Deck.js Starter][img_ds_demo] [img_ds_demo]: http://loose-bits.com/media/img/2012/11/05/deck_slides.png