This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation, and mobile-friendly responsive design. It is configurable, extensible, and can use any number of different Bootswatch CSS themes.
.. _Bootstrap: http://getbootstrap.com/ .. _Sphinx: http://sphinx-doc.org/ .. _theme: http://sphinx-doc.org/theming.html .. _PyPI: http://pypi.python.org/pypi/sphinx-bootstrap-theme/ .. _GitHub repository: https://github.com/ryan-roemer/sphinx-bootstrap-theme
The theme is introduced and discussed in the following posts:
Twitter Bootstrap Theme for Sphinx <http://loose-bits.com/2011/12/09/sphinx-twitter-bootstrap-theme.html>
_Sphinx Bootstrap Theme Updates - Mobile, Dropdowns, and More <http://loose-bits.com/2012/11/19/sphinx-bootstrap-theme-updates.html>
_Sphinx Bootstrap Theme 0.1.6 - Bootstrap and Other Updates <http://loose-bits.com/2013/02/12/sphinx-bootstrap-theme-updates.html>
_Sphinx Bootstrap Theme 0.2.0 - Now with Bootswatch! <http://loose-bits.com/2013/04/10/sphinx-bootstrap-theme-bootswatch.html>
_Sphinx Bootstrap Theme 0.3.0 - Bootstrap v3 and more! <http://loose-bits.com/2013/09/08/sphinx-bootstrap-theme-bootstrap-3.html>
_Examples of the theme in use for some public projects:
Sphinx Bootstrap Theme
_: This project, with the theme option
'bootswatch_theme': "sandstone"
to use the "Sandstone" Bootswatch theme.Django Cloud Browser
_: A Django reusable app for browsing cloud
datastores (e.g., Amazon Web Services S3).seaborn
_: A statistical data visualization library.The theme demo website also includes an examples page
for some useful
illustrations of getting Sphinx to play nicely with Bootstrap (also take a
look at the examples source
for the underlying reStructuredText).
.. _Bootswatch: http://bootswatch.com .. _United: http://bootswatch.com/united .. _Flatly: http://bootswatch.com/flatly .. _Sandstone: http://bootswatch.com/sandstone .. _Sphinx Bootstrap Theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme .. _examples page: https://ryan-roemer.github.io/sphinx-bootstrap-theme/examples.html .. _examples source: https://ryan-roemer.github.io/sphinx-bootstrap-theme/_sources/examples.rst.txt .. _Django Cloud Browser: https://ryan-roemer.github.io/django-cloud-browser .. _seaborn: http://seaborn.pydata.org
Installation from PyPI_ is fairly straightforward:
Install the package::
$ pip install sphinx_bootstrap_theme
Edit the "conf.py" configuration file to point to the bootstrap theme::
import sphinx_bootstrap_theme
html_theme = 'bootstrap' html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
The theme can be customized in varying ways (some a little more work than others).
The theme provides many built-in options that can be configured by editing your "conf.py" file::
# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
# Path should be relative to the ``_static`` files directory.
html_logo = "my_logo.png"
# Theme options are theme-specific and customize the look and feel of a
# theme further.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
'navbar_title': "Demo",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Site",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
'navbar_links': [
("Examples", "examples"),
("Link", "http://example.com", True),
],
# Render the next and previous page links in navbar. (Default: true)
'navbar_sidebarrel': True,
# Render the current pages TOC in the navbar. (Default: true)
'navbar_pagenav': True,
# Tab name for the current pages TOC. (Default: "Page")
'navbar_pagenav_name': "Page",
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
'navbar_class': "navbar navbar-inverse",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "nav",
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing (default) or the name of a valid theme
# such as "cosmo" or "sandstone".
#
# The set of valid themes depend on the version of Bootstrap
# that's used (the next config option).
#
# Currently, the supported themes are:
# - Bootstrap 2: https://bootswatch.com/2
# - Bootstrap 3: https://bootswatch.com/3
'bootswatch_theme': "united",
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
Note for the navigation bar title that if you don't specify a theme option of
navbar_title
that the "conf.py" project
string will be used. We don't
use the html_title
or html_short_title
values because by default those
both contain version strings, which the navigation bar treats differently.
The theme supports Bootstrap v2.3.2
and v3.3.7
via the
bootstrap_version
theme option (of "2"
or "3"
). Some notes
regarding version differences:
sub-menus
_, so while supported by this
theme, they will not show up in site or page menus... _sub-menus
: http://stackoverflow.com/questions/18023493
As a more "hands on" approach to customization, you can override any template
in this Sphinx theme or any others. A good candidate for changes is
"layout.html", which provides most of the look and feel. First, take a look
at the "layout.html" file that the theme provides, and figure out
what you need to override. As a side note, we have some theme-specific
enhancements, such as the navbarextra
template block for additional
content in the navbar.
Then, create your own "_templates" directory and "layout.html" file (assuming you build from a "source" directory)::
$ mkdir source/_templates
$ touch source/_templates/layout.html
Then, configure your "conf.py"::
templates_path = ['_templates']
Finally, edit your override file "source/_templates/layout.html"::
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{# Add some extra stuff before and use existing with 'super()' call. #}
{% block footer %}
<h2>My footer of awesomeness.</h2>
{{ super() }}
{% endblock %}
Alternately, you could add your own custom static media directory with a CSS file to override a style, which in the demo would be something like::
$ mkdir source/_static
$ touch source/_static/my-styles.css
In the new file "source/_static/my-styles.css", add any appropriate styling, e.g. a bold background color::
footer {
background-color: red;
}
Then, in "conf.py", edit this line::
html_static_path = ["_static"]
From there it depends on which version of Sphinx you are using:
Sphinx <= 1.5
You will need the override template "source/_templates/layout.html" file configured as above, but with the following code::
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{# Custom CSS overrides #}
{% set css_files = css_files + ['_static/my-styles.css'] %}
.. note::
See Issue #159 <https://github.com/ryan-roemer/sphinx-bootstrap-theme/pull/159>
_
for more information.
Sphinx >= 1.6.1
Add a setup
function in "conf.py" with stylesheet paths added relative to the
static path::
def setup(app):
app.add_stylesheet("my-styles.css") # also can be a full URL
# app.add_stylesheet("ANOTHER.css")
# app.add_stylesheet("AND_ANOTHER.css")
.. tip::
Sphinx automatically calls your setup
function defined in "conf.py" during
the build process for you. There is no need to, nor should you, call this
function directly in your code.
The theme places the global TOC, local TOC, navigation (prev, next) and source links all in the top Bootstrap navigation bar, along with the Sphinx search bar on the left side.
The global (site-wide) table of contents is the "Site" navigation dropdown,
which is a configurable level rendering of the toctree
for the entire site.
The local (page-level) table of contents is the "Page" navigation dropdown,
which is a multi-level rendering of the current page's toc
.
The theme offers Bootstrap v2.x and v3.x, both of which rely on
jQuery v.1.9.x. As the jQuery that Bootstrap wants can radically depart from
the jQuery Sphinx internal libraries use, the library from this theme is
integrated via noConflict()
as $jqTheme
.
You can override any static JS/CSS files by dropping different versions in your Sphinx "_static" directory.
Contributions to this project are most welcome. Please make sure that the demo
site builds cleanly, and looks like what you want. This project uses tox <https://tox.readthedocs.io/en/latest/>
_ for development, once you have tox
installed (e.g., pip install tox
), change directories to the
sphinx-bootstrap-theme
top-level directory.
tox -e docs
tox -e linkcheck
tox -e lint
The encouraged way to develop with this package is to use a development server. Changes made to files local in the repository will require rebuilding the demo website, and using the development server will automate this process.
In your terminal, execute tox -e server
from the top level directory.
By default, this runs on port 8000
. If this port is in use, a
pass-through argument to the underlying sphinx-autobuild <https://github.com/executablebooks/sphinx-autobuild>
_ tool is required
such as tox -e server -- -p 8080
. The --
between server
and
-p
are required, that signals the end of the arguments to tox
and
everything after gets fed to sphinx-autobuild
.
Open your browser of choice and visit http://127.0.0.1:8000/ <http://127.0.0.1:8000/>
_ to see the server.
Make any intended edits to the files in this repository. After the server finishes rebuilding you can refresh your browser to see the updates.
When finished, make sure to end the server from your terminal you ran
tox -e server
with by issuing ctrl+c
.
When a tag is pushed of the form vX.Y.Z
(with the starting v
), it will
build the distribution using tox -e dist
and upload to PyPI automatically.
Before pushing a tag, using Test PyPI should be done. In addition to tox
,
install twine <https://twine.readthedocs.io/en/latest/>
_
(pip install twine
).
.. code-block:: console
# Build the distribution locally.
$ tox -e dist
# Attempt uploading to Test PyPI
$ twine upload -r testpypi dist/*
.. note::
The file ``sphinx_bootstrap_theme/__init__.py`` has the version number that
will be created. **Make sure it matches the tag you are creating**, once
an upload goes up it cannot be overwritten. If in preparing a release you
find an error and need to rebuild, simply increase the ``dev`` version
in ``__init__.py`` and then rebuild and reupload. For example:
.. code-block:: diff
--- a/sphinx_bootstrap_theme/__init__.py
+++ b/sphinx_bootstrap_theme/__init__.py
@@ -1,7 +1,7 @@
"""Sphinx bootstrap theme."""
import os
-__version__ = "0.8.0.dev0"
+__version__ = "0.8.0.dev1"
After verifying that everything appears as desired on Test PyPI <https://test.pypi.org/project/sphinx-bootstrap-theme/>
_ at the project
URL, one can also test the installation if desired: pip install --index-url https://test.pypi.org/simple/ sphinx-bootstrap-theme
Now that everything is validated, we are ready for release.
Set the version number in sphinx_bootstrap_theme/__init__.py
correctly.
E.g., for release 0.8.0
, set __version__ = "0.8.0"
without the
trailing dev
qualifier.
If desired, rebuild and upload to Test PyPI. Commit and push the changed
version number. Tag this commit git tag v0.8.0
(note the leading v
is required for the CI/CD), and git push --tags
. This should initiate
the official release and upload it to PyPI (see the files
.github/workflows/{package,github_pages}.yaml
for more).
Now that the release is out, update the version number so that any users
installing from source do not believe they have an official release. E.g.,
set __version__ = "0.8.1.dev0"
, commit and push this "dev version bump"
online.
Sphinx Bootstrap Theme is licensed under the MIT_ license.
Bootstrap v2
_ is licensed under the Apache license 2.0.
Bootstrap v3.1.0+
_ is licensed under the MIT license.
.. MIT
: https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/master/LICENSE.txt
.. Bootstrap v2
: https://github.com/twbs/bootstrap/blob/v2.3.2/LICENSE
.. _Bootstrap v3.1.0+
: https://github.com/twbs/bootstrap/blob/master/LICENSE