Upgrade to bootstrap / bootswatch v3.3.7 (#164)

- minor doc fixes
    - I believe I got all 3.3.6 into 3.3.7
    - suggestion to use bs3 over 2
- more specific directions on how to upgrade in future
    - missing documentation of `static/bootstrap-sphinx.css_t` for upgrades
    - much more description of what should go down in `TODO.rst`
        - modified the **epic** `tar` packaging to be more explicit (anybody who has `egrep` aliased can't use the original solution)
- fixed `Makefile` to actually use `python3`
    - added simple option for port override (I'm currently running a mission critical app on `8000` xD)
- fixed `requirements.txt` to allow e.g. `sphinx==1.6.2` or higher
    - `setup.py` has neither of these dependencies?
    - if you add them, you'll need to treat python 2 and 3 separately because of fabric?

#### Notes:

- Candidate to close #149
- Officially the `solar` theme is not in the `v3.3.7` bootswatch tag, see [this issue](thomaspark/bootswatch#643)
    - Just added it manually from the main page
- I don't think you actually want to include the `custom` theme, I'm pretty sure it's either an artifact or a basis for creating your own.
- Changed a few locations referring to the now nonexistent `amelia` theme
 
#### Questions:

1. There is a rather long commented out section in `TODO.rst`.  Might be worth deleting?
2. See changes to `README.rst`, in particular the added `.. warning::`.  The question: I didn't really understand what was going on with #159 because I didn't have any trouble building with `sphinx==1.5.1` or `1.5.5` etc.  Basically, if it's actually a hard requirement then maybe the verbiage is fine, but if not then it's too strong?
3. This is not a "you" problem, but when viewing the source of generated pages I noticed all of the javascript gets loaded at the beginning in the `<meta>` rather than at the bottom.  I know next to nothing about front-end, but those are supposed to be loaded last right (sphinx is doing this, not you)?

Happy to undo / revise any of the included, thanks again for the theme 😄

.gitignore

@@ -1,9 +1,11 @@
-\.DS_Store
-*\.pyc
+.DS_Store
+*.pyc
 
 build
 dist
-*\.egg-info
+*.egg-info
 demo/build/*
 node_modules
 __pycache__
+.vscode
+

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)

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

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

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

requirements.txt

@@ -1,2 +1,2 @@
-Fabric==1.6.0
-Sphinx==1.6.1
+Fabric>=1.13.2
+Sphinx>=1.6.1

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