bpo-30607: Use external python-doc-theme (GH-2017)

Author: Jon Wayne Parrott

.travis.yml

@@ -49,7 +49,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 blurb
+        # 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 blurb python-docs-theme
       script:
         - make check suspicious html SPHINXOPTS="-q -W -j4"
     - os: osx

Doc/Makefile

@@ -123,7 +123,7 @@ clean:
 
 venv:
 	$(PYTHON) -m venv $(VENVDIR)
-	$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb
+	$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb python-docs-theme
 	@echo "The venv has been created in the $(VENVDIR) directory"
 
 dist:

Doc/README.rst

@@ -20,11 +20,11 @@ tree but are maintained separately and are available from
 
 * `Sphinx <https://pypi.org/project/Sphinx/>`_
 * `blurb <https://pypi.org/project/blurb/>`_
+* `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
 
 The easiest way to install these tools is to create a virtual environment and
 install the tools into there.
 
-
 Using make
 ----------
 

Doc/conf.py

@@ -46,9 +46,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);
+});