bpo-30607: Use external python-doc-theme

Author: Jon Wayne Parrott

.travis.yml

@@ -37,7 +37,8 @@ matrix:
         - cd Doc
         # Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
         # (Updating the version is fine as long as no warnings are raised by doing so.)
-        - python -m pip install sphinx~=1.6.1
+        # The theme used by the docs is stored seperately, so we need to install that as well.
+        - python -m pip install sphinx~=1.6.1 git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
       script:
         - make check suspicious html SPHINXOPTS="-q -W -j4"
     - os: linux

Doc/README.rst

@@ -14,10 +14,15 @@ developers guide.
 Building the docs
 =================
 
-You need to have `Sphinx <http://sphinx-doc.org/>`_ installed; it is the toolset
-used to build the docs.  It is not included in this tree, but maintained
-separately and `available from PyPI <https://pypi.python.org/pypi/Sphinx>`_.
-
+You need to have `Sphinx <http://sphinx-doc.org/>`_ and the Sphinx theme for Python
+docs installed. Sphinx is the toolset used to build the docs, it is not
+included in this tree, but maintained separately and
+`available from PyPI <https://pypi.python.org/pypi/Sphinx>`_. The theme is
+likewise separately maintained and is
+`available from GitHub <https://github.com/python/python-docs-theme>`_. You
+can install both using ``pip``::
+
+    python -m pip install sphinx~=1.6.1 git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
 
 Using make
 ----------

Doc/conf.py

@@ -45,9 +45,13 @@
 # -----------------------
 
 # Use our custom theme.
-html_theme = 'pydoctheme'
+html_theme = 'python_docs_theme'
 html_theme_path = ['tools']
-html_theme_options = {'collapsiblesidebar': True}
+html_theme_options = {
+    'collapsiblesidebar': True,
+    'issues_url': 'https://docs.python.org/3/bugs.html',
+    'root_include_title': False   # We use the version switcher instead.
+}
 
 # Short title used e.g. for <title> HTML tags.
 html_short_title = '%s Documentation' % release

Doc/tools/pydoctheme/static/pydoctheme.css

@@ -0,0 +1,53 @@
+$(document).ready(function() {
+    // add the search form and bind the events
+    $('h1').after([
+      '<p>Filter entries by content:',
+      '<input type="text" value="" id="searchbox" style="width: 50%">',
+      '<input type="submit" id="searchbox-submit" value="Filter"></p>'
+    ].join('\n'));
+
+    function dofilter() {
+        try {
+            var query = new RegExp($('#searchbox').val(), 'i');
+        }
+        catch (e) {
+            return; // not a valid regex (yet)
+        }
+        // find headers for the versions (What's new in Python X.Y.Z?)
+        $('#changelog h2').each(function(index1, h2) {
+            var h2_parent = $(h2).parent();
+            var sections_found = 0;
+            // find headers for the sections (Core, Library, etc.)
+            h2_parent.find('h3').each(function(index2, h3) {
+                var h3_parent = $(h3).parent();
+                var entries_found = 0;
+                // find all the entries
+                h3_parent.find('li').each(function(index3, li) {
+                    var li = $(li);
+                    // check if the query matches the entry
+                    if (query.test(li.text())) {
+                        li.show();
+                        entries_found++;
+                    }
+                    else {
+                        li.hide();
+                    }
+                });
+                // if there are entries, show the section, otherwise hide it
+                if (entries_found > 0) {
+                    h3_parent.show();
+                    sections_found++;
+                }
+                else {
+                    h3_parent.hide();
+                }
+            });
+            if (sections_found > 0)
+                h2_parent.show();
+            else
+                h2_parent.hide();
+        });
+    }
+    $('#searchbox').keyup(dofilter);
+    $('#searchbox-submit').click(dofilter);
+});