Install and use sphinx-bootstrap-theme on Ubuntu 14.04
Jul 7, 2014
warning
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 conf.py 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 conf.py
file that contains the Sphinx options for generating html, pdf, etc output. The
minimal changes to conf.py
in order to get the bootstrap theme working are in the
{% sbUrl refs["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 Makefile
to
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.