Skip to content

Latest commit

 

History

History
153 lines (111 loc) · 5.48 KB

README.rst

File metadata and controls

153 lines (111 loc) · 5.48 KB
Raw

Sphinx Bootstrap Theme

This Sphinx theme integrates the Twitter Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation, and mobile-friendly responsive design.

Introduction and Demos

The theme is introduced and discussed in two blog posts:

Here is the theme in use for some of my public projects:

  • Sphinx Bootstrap Theme: This project, with a dark top navbar, using the theme option 'navbar_class': "navbar navbar-inverse".
  • Django Cloud Browser: A Django reusable app for browsing cloud datastores (e.g., Amazon Web Services S3).

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).

Installation

Installation from PyPI is fairly straightforward:

  1. Install the package:

    $ pip install sphinx_bootstrap_theme

  2. Edit the "conf.py" configuration file to point to the bootstrap theme:

    # At the top.
import sphinx_bootstrap_theme

# ...

# Activate the theme.
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

Customization

The theme can be further customized with the following options by editing the "conf.py" configuration:

# (Optional) Use a shorter name to conserve nav. bar space.
html_short_title = "Demo"

# (Optional) Logo. Should be exactly 24x24 px to fit the nav. bar.
# 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 = {
    # Global TOC depth for "site" navbar tab. (Default: 1)
    # Switching to -1 shows all levels.
    'globaltoc_depth': 2,

    # 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",
}

Theme Notes

Sphinx

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.

Bootstrap

The theme uses Twitter Bootstrap v2.2.1. You can override any static JS/CSS files by dropping different versions in your Sphinx "_static" directory.

Licenses

Sphinx Bootstrap Theme is licensed under the MIT license.

Twitter Bootstrap is licensed under the Apache license.