Sphinx Bootstrap Theme

Overview

Sphinx Bootstrap Theme

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.

Introduction and Demos

The theme is introduced and discussed in the following posts:

Examples of the theme in use for some public projects:

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 customized in varying ways (some a little more work than others).

Theme Options

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.

Bootstrap Versions

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:

  • Bootstrap 3 has dropped support for sub-menus, so while supported by this theme, they will not show up in site or page menus.
  • Internally, "navbar.html" is the Sphinx template used for Bootstrap v3 and "navbar-2.html" is the template used for v2.
  • If you are unsure what to choose, choose Bootstrap 3. If you experience some form of compatibility issues, then try and use Bootstrap 2.

Extending "layout.html"

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 %}

Adding Custom CSS

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

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

Contributing

Contributions to this project are most welcome. Please make sure that the demo site builds cleanly, and looks like what you want. We suggest using pipenv to build this project:

$ cd sphinx-bootstrap-theme
$ pipenv install --dev

Before working in this project directory, do:

$ pipenv shell

Next, build the demo:

$ fab clean && fab demo

Then, view the site in the development server:

$ fab demo_server

Also, if you are adding a new type of styling or Sphinx or Bootstrap construct, please add a usage example to the "Examples" page.

Note: If you are in Python 3, Fabric isn't available, so we have a very rough Makefile in its place. Try:

$ make clean && make demo

Then, view the site in the development server:

$ make demo_server

Licenses

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.

Owner
Ryan Roemer
Software geek, former patent attorney, & co-founder of @FormidableLabs. Curator of @SeaNode.
Ryan Roemer
An introduction course for Python provided by VetsInTech

Introduction to Python This is an introduction course for Python provided by VetsInTech. For every "boot camp", there usually is a pre-req, but becaus

Vets In Tech 2 Dec 02, 2021
A simple USI Shogi Engine written in python using python-shogi.

Revengeshogi My attempt at creating a USI Shogi Engine in python using python-shogi. Current State of Engine Currently only generating random moves us

1 Jan 06, 2022
This is a small project written to help build documentation for projects in less time.

Documentation-Builder This is a small project written to help build documentation for projects in less time. About This project builds documentation f

Tom Jebbo 2 Jan 17, 2022
💡 Catatan Materi Bahasa Pemrogramman Python

Repository catatan kuliah Andika Tulus Pangestu selama belajar Dasar Pemrograman dengan Python.

0 Oct 10, 2021
The purpose of this project is to share knowledge on how awesome Streamlit is and can be

Awesome Streamlit The fastest way to build Awesome Tools and Apps! Powered by Python! The purpose of this project is to share knowledge on how Awesome

Marc Skov Madsen 1.5k Jan 07, 2023
FxBuzzly - Buzzly.art links do not embed in Discord, this fixes them (rudimentarily)

fxBuzzly Buzzly.art links do not embed in Discord, this fixes them (rudimentaril

Dania Rifki 2 Oct 27, 2022
Yu-Gi-Oh! Master Duel translation script

Yu-Gi-Oh! Master Duel translation script

715 Jan 08, 2023
Collection of Summer 2022 tech internships!

Collection of Summer 2022 tech internships!

Pitt Computer Science Club (CSC) 15.6k Jan 03, 2023
swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.

Master (2.4.25-SNAPSHOT): 3.0.31-SNAPSHOT: Maven Central ⭐ ⭐ ⭐ If you would like to contribute, please refer to guidelines and a list of open tasks. ⭐

Swagger 15.2k Dec 31, 2022
Docov - Light-weight, recursive docstring coverage analysis for python modules

docov Light-weight, recursive docstring coverage analysis for python modules. Ov

Richard D. Paul 3 Feb 04, 2022
Fast, efficient Blowfish cipher implementation in pure Python (3.4+).

blowfish This module implements the Blowfish cipher using only Python (3.4+). Blowfish is a block cipher that can be used for symmetric-key encryption

Jashandeep Sohi 41 Dec 31, 2022
A Python library for setting up projects using tabular data.

A Python library for setting up projects using tabular data. It can create project folders, standardize delimiters, and convert files to CSV from either individual files or a directory.

0 Dec 13, 2022
learn python in 100 days, a simple step could be follow from beginner to master of every aspect of python programming and project also include side project which you can use as demo project for your personal portfolio

learn python in 100 days, a simple step could be follow from beginner to master of every aspect of python programming and project also include side project which you can use as demo project for your

BDFD 6 Nov 05, 2022
A complete kickstart devcontainer repository for python3

A complete kickstart devcontainer repository for python3

Viktor Freiman 3 Dec 23, 2022
Poetry plugin to export the dependencies to various formats

Poetry export plugin This package is a plugin that allows the export of locked packages to various formats. Note: For now, only the requirements.txt f

Poetry 90 Jan 05, 2023
A Sublime Text plugin to select a default syntax dialect

Default Syntax Chooser This Sublime Text 4 plugin provides the set_default_syntax_dialect command. This command manipulates a syntax file (e.g.: SQL.s

3 Jan 14, 2022
Plotting and analysis tools for ARTIS simulations

Artistools Artistools is collection of plotting, analysis, and file format conversion tools for the ARTIS radiative transfer code. Installation First

ARTIS Monte Carlo Radiative Transfer 8 Nov 07, 2022
Build AGNOS, the operating system for your comma three

agnos-builder This is the tool to build AGNOS, our Ubuntu based OS. AGNOS runs on the comma three devkit. NOTE: the edk2_tici and agnos-firmare submod

comma.ai 21 Dec 24, 2022
Ultimaker Cura 2 Mooraker Upload Plugin

Klipper & Cura - Cura2MoonrakerPlugin Allows you to upload Gcode directly from Cura to your Klipper-based 3D printer (Fluidd, Mainsailos etc.) using t

214 Jan 03, 2023
ACPOA plugin creation helper

ACPOA Plugin What is ACPOA ACPOA is the acronym for "Application Core for Plugin Oriented Applications". It's a tool to create flexible and extendable

Leikt Sol'Reihin 1 Oct 20, 2021