Install and use sphinx-bootstrap-theme on Ubuntu 14.04
Jul 7, 2014
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
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 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 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
generate the html. The command, and resulting output should look something
$ 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 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.