ryan-roemer · ryan-roemer · Jul 23, 2017 · Jul 21, 2017 · Jul 22, 2017 · Jul 22, 2017
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,11 @@
-\.DS_Store
-*\.pyc
+.DS_Store
+*.pyc
 
 build
 dist
-*\.egg-info
+*.egg-info
 demo/build/*
 node_modules
 __pycache__
+.vscode
+
diff --git a/Makefile b/Makefile
@@ -12,5 +12,10 @@ clean:
 demo:
 	cd demo && make html
 
-demo_server:
-	cd demo/build/html && python -m http.server 8000
+# PORT allows you to specify a different port if say
+# port 8000 is currently in use
+#
+# make demo_server PORT=8080
+PORT ?= 8000
+demo_server: demo
+	cd demo/build/html && python3 -m http.server $(PORT)
diff --git a/README.rst b/README.rst
@@ -138,7 +138,7 @@ your "conf.py" file::
         # Bootswatch (http://bootswatch.com/) theme.
         #
         # Options are nothing (default) or the name of a valid theme
-        # such as "amelia" or "cosmo".
+        # such as "cosmo" or "sandstone".
         'bootswatch_theme': "united",
 
         # Choose Bootstrap version.
@@ -153,14 +153,16 @@ both contain version strings, which the navigation bar treats differently.
 
 Bootstrap Versions
 ------------------
-The theme supports Bootstrap ``v2.3.2`` and ``v3.3.4`` via the
+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.
 
 .. _`sub-menus`: http://stackoverflow.com/questions/18023493
 
@@ -228,16 +230,27 @@ configured as above, but with the following code::
     {# Custom CSS overrides #}
     {% set css_files = css_files + ['_static/my-styles.css'] %}
 
-**Sphinx >= 1.6**
+.. note::
 
-Add a `setup` function in "conf.py" with stylesheet paths added relative to the
+   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.
+
 Theme Notes
 ===========
 Sphinx

diff --git a/TODO.rst b/TODO.rst
@@ -50,21 +50,176 @@ Infrastructure
 Upgrade Notes
 =============
 
-Get new ``bootstrap-VERSION`` and drop in ``bootstrap/static``.
-
-Manually grep and replace instances of ``jQuery`` with
-``(window.$jqTheme || window.jQuery)`` in files in the new
-`bootstrap-VERSION/js` directory.
-
-Update ``VERSION`` in ``sphinx_bootstrap_theme/bootstrap/layout.html``
-
-Update bootswatch:
+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
+------------------
+
+1. Get new ``bootstrap-VERSION`` and drop in ``bootstrap/static``.
+
+   - New versions should be available `here <http://getbootstrap.com/getting-started/#download>`_.
+   - Choose "Bootstrap":
+
+     ..
+
+        Compiled and minified CSS, JavaScript, and fonts.  No docs or original
+        source files are included.
+
+2. Manually grep and replace instances of ``(jQuery)`` with
+   ``(window.$jqTheme || window.jQuery)`` in files in the new
+   ``bootstrap-VERSION/js`` directory.  See below.
+
+3. Update ``VERSION`` in ``sphinx_bootstrap_theme/bootstrap/layout.html``:
+
+   .. code-block:: jinja
+
+      {% 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 %}
+
+4. Update ``VERSION`` in ``sphinx_bootstrap_theme/bootstrap/static/bootstrap-sphinx.css_t``
+
+   .. code-block:: jinja
+
+      {% 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).
+
+.. code-block:: console
+
+   # 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!
 
 .. code-block:: bash
 
-    # Create tarball of everything for bootswatch to drop in and replace.
-    $ cd scm/vendor/bootswatch
-    $ git checkout v3.3.6+1
-    $ find . -name "bootstrap.min.css" | \
-      (echo "./fonts" && egrep -v "\/2|bower_components\/") | \
-      xargs tar cf - > ~/Desktop/bootswatch-3.3.6.tar
+    # 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
diff --git a/demo/source/conf.py b/demo/source/conf.py
@@ -140,7 +140,7 @@
     # Bootswatch (http://bootswatch.com/) theme.
     #
     # Options are nothing (default) or the name of a valid theme such
-    # as "amelia" or "cosmo".
+    # such as "cosmo" or "sandstone".
     #
     # Example themes:
     # * flatly

diff --git a/requirements.txt b/requirements.txt
@@ -1,2 +1,2 @@
-Fabric==1.6.0
-Sphinx==1.6.1
+Fabric>=1.13.2
+Sphinx>=1.6.1
diff --git a/sphinx_bootstrap_theme/bootstrap/layout.html b/sphinx_bootstrap_theme/bootstrap/layout.html
@@ -1,7 +1,7 @@
 {% extends "basic/layout.html" %}
 
 {% if theme_bootstrap_version == "3" %}
-  {% set bootstrap_version, navbar_version = "3.3.6", "" %}
+  {% set bootstrap_version, navbar_version = "3.3.7", "" %}
   {% set bs_span_prefix = "col-md-" %}
 {% else %}
   {% set bootstrap_version, navbar_version = "2.3.2", "-2" %}

diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap-theme.min.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap-theme.min.css.map
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.css.map
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.min.css b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.min.css
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.min.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/css/bootstrap.min.css.map
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/js/bootstrap.min.js b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.6/js/bootstrap.min.js
diff --git a/...c/bootstrap-3.3.6/css/bootstrap-theme.css → ...c/bootstrap-3.3.7/css/bootstrap-theme.css b/...c/bootstrap-3.3.6/css/bootstrap-theme.css → ...c/bootstrap-3.3.7/css/bootstrap-theme.css
diff --git a/...otstrap-3.3.6/css/bootstrap-theme.css.map → ...otstrap-3.3.7/css/bootstrap-theme.css.map b/...otstrap-3.3.6/css/bootstrap-theme.css.map → ...otstrap-3.3.7/css/bootstrap-theme.css.map
diff --git a/...otstrap-3.3.6/css/bootstrap-theme.min.css → ...otstrap-3.3.7/css/bootstrap-theme.min.css b/...otstrap-3.3.6/css/bootstrap-theme.min.css → ...otstrap-3.3.7/css/bootstrap-theme.min.css
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap-theme.min.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap-theme.min.css.map
diff --git a/.../static/bootstrap-3.3.6/css/bootstrap.css → .../static/bootstrap-3.3.7/css/bootstrap.css b/.../static/bootstrap-3.3.6/css/bootstrap.css → .../static/bootstrap-3.3.7/css/bootstrap.css
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.css.map
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.min.css b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.min.css
diff --git a/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.min.css.map b/sphinx_bootstrap_theme/bootstrap/static/bootstrap-3.3.7/css/bootstrap.min.css.map
diff --git a/....6/fonts/glyphicons-halflings-regular.eot → ....7/fonts/glyphicons-halflings-regular.eot b/....6/fonts/glyphicons-halflings-regular.eot → ....7/fonts/glyphicons-halflings-regular.eot
diff --git a/....6/fonts/glyphicons-halflings-regular.svg → ....7/fonts/glyphicons-halflings-regular.svg b/....6/fonts/glyphicons-halflings-regular.svg → ....7/fonts/glyphicons-halflings-regular.svg
diff --git a/....6/fonts/glyphicons-halflings-regular.ttf → ....7/fonts/glyphicons-halflings-regular.ttf b/....6/fonts/glyphicons-halflings-regular.ttf → ....7/fonts/glyphicons-halflings-regular.ttf
diff --git a/...6/fonts/glyphicons-halflings-regular.woff → ...7/fonts/glyphicons-halflings-regular.woff b/...6/fonts/glyphicons-halflings-regular.woff → ...7/fonts/glyphicons-halflings-regular.woff
diff --git a/.../fonts/glyphicons-halflings-regular.woff2 → .../fonts/glyphicons-halflings-regular.woff2 b/.../fonts/glyphicons-halflings-regular.woff2 → .../fonts/glyphicons-halflings-regular.woff2