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

..
  The theme can be installed from PyPI_ or downloaded as a zip file from
  GitHub.

  Install Python Package from PyPI
  --------------------------------

  Download Zip Bundle
  -------------------
  To install the theme from a bundled zip file, download the theme
  bundle from the theme website and update your configuration:

  1. Create a "_themes" directory in your project source root.
  2. Get the "bootstrap" theme either as raw files or as a zipfile.

     a. Most current way is to just clone this repo or download the full
        repo source and move the "bootstrap" directory to "_themes".
     b. Alternatively, there are some prepackaged theme zip files (containing
        only the theme files), which can be read directly by Sphinx. See the
        downloads_ page for available packages. Then download
        "bootstrap.zip"::

          $ cd /path/to/_themes
          $ wget https://github.com/ryan-roemer/sphinx-bootstrap-theme/_static/downloads/bootstrap.zip

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

        # Activate the theme.
        sys.path.append(os.path.abspath('_themes'))
        html_theme = 'bootstrap'
        html_theme_path = ['_themes']

  .. _downloads: http://ryan-roemer.github.com/sphinx-bootstrap-theme/downloads.html

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

1. Get new ``bootstrap-VERSION`` and drop in ``bootstrap/static``.

   - New versions should be available `here <https://getbootstrap.com/>`_.
   - 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

    # 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
