Update python-docs-theme to work with Sphinx 5 & 6

python_docs_theme/__init__.py

@@ -52,12 +52,11 @@ def _html_page_context(
 
 def setup(app):
     current_dir = os.path.abspath(os.path.dirname(__file__))
-    app.add_html_theme(
-        'python_docs_theme', current_dir)
+    app.add_html_theme("python_docs_theme", current_dir)
 
     app.connect("html-page-context", _html_page_context)
 
     return {
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
     }

python_docs_theme/static/copybutton.js

@@ -1,64 +1,92 @@
-$(document).ready(function() {
-    /* Add a [>>>] button on the top-right corner of code samples to hide
+// ``function*`` denotes a generator in JavaScript, see
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
+function* getHideableCopyButtonElements(rootElement) {
+    // yield all elements with the "go" (Generic.Output),
+    // "gp" (Generic.Prompt), or "gt" (Generic.Traceback) CSS class
+    for (const el of rootElement.querySelectorAll('.go, .gp, .gt')) {
+        yield el
+    }
+    // tracebacks (.gt) contain bare text elements that need to be
+    // wrapped in a span to hide or show the element
+    for (let el of rootElement.querySelectorAll('.gt')) {
+        while ((el = el.nextSibling) && el.nodeType !== Node.DOCUMENT_NODE) {
+            // stop wrapping text nodes when we hit the next output or
+            // prompt element
+            if (el.nodeType === Node.ELEMENT_NODE && el.matches(".gp, .go")) {
+                break
+            }
+            // if the node is a text node with content, wrap it in a
+            // span element so that we can control visibility
+            if (el.nodeType === Node.TEXT_NODE && el.textContent.trim()) {
+                const wrapper = document.createElement("span")
+                el.after(wrapper)
+                wrapper.appendChild(el)
+                el = wrapper
+            }
+            yield el
+        }
+    }
+}
+
+
+const loadCopyButton = () => {
+    /* Add a [>>>] button in the top-right corner of code samples to hide
      * the >>> and ... prompts and the output and thus make the code
      * copyable. */
-    var div = $('.highlight-python .highlight,' +
-                '.highlight-python3 .highlight,' +
-                '.highlight-pycon .highlight,' +
-                '.highlight-pycon3 .highlight,' +
-                '.highlight-default .highlight');
-    var pre = div.find('pre');
+    const hide_text = "Hide the prompts and output"
+    const show_text = "Show the prompts and output"
 
-    // get the styles from the current theme
-    pre.parent().parent().css('position', 'relative');
-    var hide_text = 'Hide the prompts and output';
-    var show_text = 'Show the prompts and output';
-    var border_width = pre.css('border-top-width');
-    var border_style = pre.css('border-top-style');
-    var border_color = pre.css('border-top-color');
-    var button_styles = {
-        'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
-        'border-color': border_color, 'border-style': border_style,
-        'border-width': border_width, 'color': border_color, 'text-size': '75%',
-        'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em',
-        'border-radius': '0 3px 0 0'
+    const button = document.createElement("span")
+    button.classList.add("copybutton")
+    button.innerText = ">>>"
+    button.title = hide_text
+    button.dataset.hidden = "false"
+    const buttonClick = event => {
+        // define the behavior of the button when it's clicked
+        event.preventDefault()
+        const buttonEl = event.currentTarget
+        const codeEl = buttonEl.nextElementSibling
+        if (buttonEl.dataset.hidden === "false") {
+            // hide the code output
+            for (const el of getHideableCopyButtonElements(codeEl)) {
+                el.hidden = true
+            }
+            buttonEl.title = show_text
+            buttonEl.dataset.hidden = "true"
+        } else {
+            // show the code output
+            for (const el of getHideableCopyButtonElements(codeEl)) {
+                el.hidden = false
+            }
+            buttonEl.title = hide_text
+            buttonEl.dataset.hidden = "false"
+        }
     }
 
+    const highlightedElements = document.querySelectorAll(
+        ".highlight-python .highlight,"
+        + ".highlight-python3 .highlight,"
+        + ".highlight-pycon .highlight,"
+        + ".highlight-pycon3 .highlight,"
+        + ".highlight-default .highlight"
+    )
+
     // create and add the button to all the code blocks that contain >>>
-    div.each(function(index) {
-        var jthis = $(this);
-        if (jthis.find('.gp').length > 0) {
-            var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
-            button.css(button_styles)
-            button.attr('title', hide_text);
-            button.data('hidden', 'false');
-            jthis.prepend(button);
-        }
-        // tracebacks (.gt) contain bare text elements that need to be
-        // wrapped in a span to work with .nextUntil() (see later)
-        jthis.find('pre:has(.gt)').contents().filter(function() {
-            return ((this.nodeType == 3) && (this.data.trim().length > 0));
-        }).wrap('<span>');
-    });
+    highlightedElements.forEach(el => {
+        el.style.position = "relative"
 
-    // define the behavior of the button when it's clicked
-    $('.copybutton').click(function(e){
-        e.preventDefault();
-        var button = $(this);
-        if (button.data('hidden') === 'false') {
-            // hide the code output
-            button.parent().find('.go, .gp, .gt').hide();
-            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
-            button.css('text-decoration', 'line-through');
-            button.attr('title', show_text);
-            button.data('hidden', 'true');
-        } else {
-            // show the code output
-            button.parent().find('.go, .gp, .gt').show();
-            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
-            button.css('text-decoration', 'none');
-            button.attr('title', hide_text);
-            button.data('hidden', 'false');
+        // if we find a console prompt (.gp), prepend the (deeply cloned) button
+        const clonedButton = button.cloneNode(true)
+        // the onclick attribute is not cloned, set it on the new element
+        clonedButton.onclick = buttonClick
+        if (el.querySelector(".gp") !== null) {
+            el.prepend(clonedButton)
         }
-    });
-});
+    })
+}
+
+if (document.readyState !== "loading") {
+    loadCopyButton()
+} else {
+    document.addEventListener("DOMContentLoaded", loadCopyButton)
+}

python_docs_theme/static/menu.js

@@ -1,55 +1,57 @@
-document.addEventListener('DOMContentLoaded', function () {
+document.addEventListener("DOMContentLoaded", function () {
 
     // Make tables responsive by wrapping them in a div and making them scrollable
-    const tables = document.querySelectorAll('table.docutils');
+    const tables = document.querySelectorAll("table.docutils")
     tables.forEach(function(table){
-        table.outerHTML = '<div class="responsive-table__container">' + table.outerHTML + '</div>'
-    });
+        table.outerHTML = '<div class="responsive-table__container">' + table.outerHTML + "</div>"
+    })
 
-    const togglerInput = document.querySelector('.toggler__input');
-    const togglerLabel = document.querySelector('.toggler__label');
-    const sideMenu = document.querySelector('.menu-wrapper');
-    const menuItems = document.querySelectorAll('.menu')
-    const doc = document.querySelector('.document');
-    const body = document.querySelector('body');
+    const togglerInput = document.querySelector(".toggler__input")
+    const togglerLabel = document.querySelector(".toggler__label")
+    const sideMenu = document.querySelector(".menu-wrapper")
+    const menuItems = document.querySelectorAll(".menu")
+    const doc = document.querySelector(".document")
+    const body = document.querySelector("body")
 
     function closeMenu() {
-        togglerInput.checked = false;
-        sideMenu.setAttribute("aria-expanded", 'false');
-        sideMenu.setAttribute('aria-hidden', 'true');
-        togglerLabel.setAttribute('aria-pressed', 'false');
-        body.style.overflow = 'visible';
+        togglerInput.checked = false
+        sideMenu.setAttribute("aria-expanded", "false")
+        sideMenu.setAttribute("aria-hidden", "true")
+        togglerLabel.setAttribute("aria-pressed", "false")
+        body.style.overflow = "visible"
     }
     function openMenu() {
-        togglerInput.checked = true;
-        sideMenu.setAttribute("aria-expanded", 'true');
-        sideMenu.setAttribute('aria-hidden', 'false');
-        togglerLabel.setAttribute('aria-pressed', 'true');
-        body.style.overflow = 'hidden';
+        togglerInput.checked = true
+        sideMenu.setAttribute("aria-expanded", "true")
+        sideMenu.setAttribute("aria-hidden", "false")
+        togglerLabel.setAttribute("aria-pressed", "true")
+        body.style.overflow = "hidden"
     }
 
     // Close menu when link on the sideMenu is clicked
-    sideMenu.addEventListener('click', function (event) {
-        let target = event.target;
-        if (target.tagName.toLowerCase() !== 'a') return;
-        closeMenu();
+    sideMenu.addEventListener("click", function (event) {
+        let target = event.target
+        if (target.tagName.toLowerCase() !== "a") {
+            return
+        }
+        closeMenu()
     })
     // Add accessibility data when sideMenu is opened/closed
-    togglerInput.addEventListener('change', function (e) {
-        togglerInput.checked ? openMenu() : closeMenu();
-    });
+    togglerInput.addEventListener("change", function (_event) {
+        togglerInput.checked ? openMenu() : closeMenu()
+    })
     // Make sideMenu links tabbable only when visible
     for(let menuItem of menuItems) {
         if(togglerInput.checked) {
-          menuItem.setAttribute('tabindex', '0');
+          menuItem.setAttribute("tabindex", "0")
         } else {
-          menuItem.setAttribute('tabindex', '-1');
+          menuItem.setAttribute("tabindex", "-1")
         }
     }
     // Close sideMenu when document body is clicked
-    doc.addEventListener('click', function () {
+    doc.addEventListener("click", function () {
         if (togglerInput.checked) {
-            closeMenu();
+            closeMenu()
         }
     })
 })

python_docs_theme/static/pydoctheme.css

@@ -104,10 +104,12 @@ div.sphinxsidebar h4 {
 }
 
 div.sphinxsidebarwrapper {
+    width: 217px;
     box-sizing: border-box;
     height: 100%;
     overflow-x: hidden;
     overflow-y: auto;
+    float: left;
 }
 
 div.sphinxsidebarwrapper > h3:first-child {
@@ -135,6 +137,33 @@ div.sphinxsidebar input[type='text'] {
     max-width: 150px;
 }
 
+#sidebarbutton {
+    /* Sphinx 4.x and earlier compat */
+    height: 100%;
+    background-color: #CCCCCC;
+    margin-left: 0;
+    color: #444444;
+    font-size: 1.2em;
+    cursor: pointer;
+    padding-top: 1px;
+    float: right;
+    display: table;
+    /* after Sphinx 4.x and earlier is dropped, only the below is needed */
+    width: 12px;
+    border-radius: 0 5px 5px 0;
+    border-left: none;
+}
+
+#sidebarbutton span {
+    /* Sphinx 4.x and earlier compat */
+    display: table-cell;
+    vertical-align: middle;
+}
+
+#sidebarbutton:hover {
+    background-color: #AAAAAA;
+}
+
 div.body {
     padding: 0 0 0 1.2em;
 }
@@ -279,6 +308,26 @@ div.genindex-jumpbox a {
     text-align: center;
 }
 
+.copybutton {
+    cursor: pointer;
+    position: absolute;
+    top: 0;
+    right: 0;
+    text-size: 75%;
+    font-family: monospace;
+    padding-left: 0.2em;
+    padding-right: 0.2em;
+    border-radius: 0 3px 0 0;
+    color: #ac9; /* follows div.body pre */
+    border-color: #ac9; /* follows div.body pre */
+    border-style: solid; /* follows div.body pre */
+    border-width: 1px; /* follows div.body pre */
+}
+
+.copybutton[data-hidden='true'] {
+    text-decoration: line-through;
+}
+
 @media (max-width: 1023px) {
     /* Body layout */
     div.body {