Future Work¶

CSS / Layout¶

Search Bar: Is aligned right inconsistently in BS2 vs. BS3.
Footnotes: Need much better styling. Maybe switch to tooltips.
Optionally move the localtoc from the top navigation bar into it’s own navbar below the page title.

Infrastructure¶

Re-enable the downloads.

Upgrade Notes¶

When upgrading, you must upgrade both Bootstrap and Bootswatch — Bootswatch releases are custom tailored to the a specific version of Bootstrap. The version of jQuery (1.11) should be OK to leave as is unless a specific issue arises.

In the below examples we are upgrading to bootstrap 3.3.7; Bootstrap 2 versions should not have a need to be changed.

Updating Bootstrap¶

Get new bootstrap-VERSION and drop in bootstrap/static.
- New versions should be available here.
- Choose “Bootstrap”:
  
  Compiled and minified CSS, JavaScript, and fonts. No docs or original source files are included.
Manually grep and replace instances of (jQuery) with (window.$jqTheme || window.jQuery) in files in the new bootstrap-VERSION/js directory. See below.

Update VERSION in sphinx_bootstrap_theme/bootstrap/layout.html:

{% if theme_bootstrap_version == "3" %}
  {% set bootstrap_version, navbar_version = "3.3.7", "" %}
  {% set bs_span_prefix = "col-md-" %}
{% else %}
  {% set bootstrap_version, navbar_version = "2.3.2", "-2" %}
  {% set bs_span_prefix = "span" %}
{% endif %}

Update VERSION in sphinx_bootstrap_theme/bootstrap/static/bootstrap-sphinx.css_t

{% if theme_bootstrap_version == "3" %}
  {% set bootstrap_version, bootstrap_additional_css = "3.3.7", "theme" %}
{% else %}
  {% set bootstrap_version, bootstrap_additional_css = "2.3.2", "responsive" %}
{% endif %}

Choose your favorite text replacement tool for step 2, we will use grep and sed. The example here will be with the file bootstrap.js for understandability (since it is not minified).

# First, locate the all of the calls to jQuery
$ grep -Hn --color=auto '(jQuery)' bootstrap.js
bootstrap.js:17:}(jQuery);
bootstrap.js:77:}(jQuery);
bootstrap.js:172:}(jQuery);
bootstrap.js:298:}(jQuery);
bootstrap.js:536:}(jQuery);
bootstrap.js:749:}(jQuery);
bootstrap.js:915:}(jQuery);
bootstrap.js:1255:}(jQuery);
bootstrap.js:1776:}(jQuery);
bootstrap.js:1885:}(jQuery);
bootstrap.js:2058:}(jQuery);
bootstrap.js:2214:}(jQuery);
bootstrap.js:2377:}(jQuery);

# Make the replacement in-place while creating
# a bootstrap.js.bak file (backup of the original)
$ sed -i.bak 's/(jQuery)/(window.$jqTheme || window.jQuery)/g' bootstrap.js

# Verify there are no more (jQuery) left, and search our replacement
# for sanity checking (all the line numbers should match up)
$ grep -Hn --color=auto '(jQuery)' bootstrap.js
$ grep -Hn --color=auto '(window.$jqTheme || window.jQuery)' bootstrap.js
bootstrap.js:17:}(window.$jqTheme || window.jQuery);
bootstrap.js:77:}(window.$jqTheme || window.jQuery);
bootstrap.js:172:}(window.$jqTheme || window.jQuery);
bootstrap.js:298:}(window.$jqTheme || window.jQuery);
bootstrap.js:536:}(window.$jqTheme || window.jQuery);
bootstrap.js:749:}(window.$jqTheme || window.jQuery);
bootstrap.js:915:}(window.$jqTheme || window.jQuery);
bootstrap.js:1255:}(window.$jqTheme || window.jQuery);
bootstrap.js:1776:}(window.$jqTheme || window.jQuery);
bootstrap.js:1885:}(window.$jqTheme || window.jQuery);
bootstrap.js:2058:}(window.$jqTheme || window.jQuery);
bootstrap.js:2214:}(window.$jqTheme || window.jQuery);
bootstrap.js:2377:}(window.$jqTheme || window.jQuery);

# IMPORTANT! Check your work!  Most of these were all in either
# comments or error strings (that we want to leave as is),
# but line 7 below needs to be updated!
#
# So line 7 should be changed (by you) to be
#
#     if (typeof (window.$jqTheme || window.jQuery) === 'undefined') {
$ grep -Hn --color=auto 'jQuery' bootstrap.js
bootstrap.js:7:if (typeof jQuery === 'undefined') {
bootstrap.js:8:  throw new Error('Bootstrap\'s JavaScript requires jQuery')
bootstrap.js:15:    throw new Error('Bootstrap\'s JavaScript requires jQuery version 1.9.1 or higher, but lower than version 4')
bootstrap.js:17:}(window.$jqTheme || window.jQuery);
bootstrap.js:77:}(window.$jqTheme || window.jQuery);
bootstrap.js:172:}(window.$jqTheme || window.jQuery);
bootstrap.js:298:}(window.$jqTheme || window.jQuery);
bootstrap.js:536:}(window.$jqTheme || window.jQuery);
bootstrap.js:749:}(window.$jqTheme || window.jQuery);
bootstrap.js:915:}(window.$jqTheme || window.jQuery);
bootstrap.js:1255:}(window.$jqTheme || window.jQuery);
bootstrap.js:1260: * Inspired by the original jQuery.tipsy by Jason Frame
bootstrap.js:1624:    // Avoid using $.offset() on SVGs since it gives incorrect results in jQuery 3.
bootstrap.js:1776:}(window.$jqTheme || window.jQuery);
bootstrap.js:1885:}(window.$jqTheme || window.jQuery);
bootstrap.js:2058:}(window.$jqTheme || window.jQuery);
bootstrap.js:2076:    // jscs:disable requireDollarBeforejQueryAssignment
bootstrap.js:2078:    // jscs:enable requireDollarBeforejQueryAssignment
bootstrap.js:2214:}(window.$jqTheme || window.jQuery);
bootstrap.js:2377:}(window.$jqTheme || window.jQuery);

# If all went according to plan, delete the backup
$ rm bootstrap.js.bak

Update Bootswatch¶

In this example we will walk through how to create the necessary structure using version 3.3.7 of Bootswatch. When updating in the future, replace 3.3.7 in the below with the version of Bootswatch you are upgrading to. Make sure that you are upgrading to the same version as Bootstrap!

# Go to a familiar working location, we choose ~/Desktop for this example
$ cd ~/Desktop

# Download the source code for bootswatch
$ git clone https://github.com/thomaspark/bootswatch.git
$ cd bootswatch

# Checkout the tagged release (use `git tag -l` to see all options)
$ git checkout v3.3.7

# We need to package every "theme/bootstrap.min.css", as well as the
# fonts directory.  In the below, we are using a clever hack to include
# the fonts directory by echoing it first so `tar` at the end will know
# to copy it.  We then want to find all bootstrap.min.css files, but
# need to ignore three directories: "2", "custom", and "bower_components".
#
# NOTE: the `echo` and `find` commands **MUST** be (in the same parentheses)
#
# You should be able to copy-paste this _without_ the leading $
$ (echo "./fonts" &&                            \
          find . -name "bootstrap.min.css"      \
              -not -path "./2/*"                \
              -not -path "./bower_components/*" \
              -not -path "./custom/*")          | \
      xargs tar -cf ~/Desktop/bootswatch-flat-3.3.7.tar

# Now that we've extracted the relevant files, add them to the
# sphinx_bootstrap_theme repo
$ cd /path/to/sphinx-bootstrap-theme/sphinx_bootstrap_theme/bootstrap/static

# Make the directory relevant to your bootswatch version and enter it;
# the archive we made is not self-contained
$ mkdir bootswatch-3.3.7
$ cd bootswatch-3.3.7

# Extract the archive we just created here
$ cat ~/Desktop/bootswatch-flat-3.3.7.tar | tar -x

# Make sure the themes you were expecting, **AND** the fonts directory are here
$ ls