Install and use sphinx-bootstrap-theme on Ubuntu 14.04


This post is more than 5 years old. While math doesn't age, code and operating systems do. Please use the code/ideas with caution and expect some issues due to the age of the content. I am keeping these posts up for archival purposes because I still find them useful for reference, even when they are out of date!

In this post I will try out the sphinx-bootstrap-theme . As the name suggests, this project combines sphinx , a Python documentation tool that generates html/pdf/etc from rst files, and bootstrap , a modern web framework from Twitter for generating responsive websites.

First, we install using pip (see my post Install Python packages on Ubuntu 14.04 if you are getting started with Python and installing packages on Ubuntu 14.04):

$ pip install --user sphinx-bootstrap-theme

We can see where it installed (and other package information) using:

$ pip show sphinx-bootstrap-theme
Name: sphinx-bootstrap-theme
Version: 0.4.0
Location: /home/cstrelioff/.local/lib/python2.7/site-packages
Requires: setuptools

First, use sphinx-quickstart to get an initial setup (I will do this in my Sandbox directory for testing things out-- you can do this wherever you like):

$ cd ~/Sandbox
$ mkdir sbt_test
$ cd sbt_test
$ sphinx-quickstart

The sphinx-quickstart asks a bunch of setup questions (you can usually select the default option by hitting Enter). After the setup, I have a directory like this:

$ ls sbt_test/
_build index.rst Makefile _static _templates

Next, I will try to follow the instructions at sphinx-bootstrap-theme to get a basic site up and running. This involves editing the file that contains the Sphinx options for generating html, pdf, etc output. The minimal changes to in order to get the bootstrap theme working are in the sphinx-bootstrap-theme installation section and involve:

  • importing the python code
  • setting the html_theme
  • setting the html_theme_path.

Once that it done, use the Makefileto generate the html. The command, and resulting output should look something like this:

$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

Now, open the index.html located in *_build/htlml to see the results. Also checkout customization of sphinx-bootstrap-theme for more ideas.