Docs update: Fix API Reference page

docs/source/_static/wakepy.js

@@ -0,0 +1,62 @@
+
+/**
+ * Function to check if we are on the API Reference page
+ * @returns {bool} True of on API Reference page. False otherwise.
+ */
+function shouldDisableScrollSpy() {
+    // The API Reference page has <h1>API Reference</h1> as the first h1 element
+    var h1Elements =  document.querySelectorAll("h1");
+    var h1Array = Array.from(h1Elements);
+    var isOnApiReferencePage = h1Array[0].textContent.trim() == 'API Reference'
+    return isOnApiReferencePage
+}
+
+/**
+ * Function to diable the Bootstrap Scroll Spy.
+ */
+function disableScrollSpy() {
+    var scrollSpyBody = document.querySelector('body[data-bs-spy="scroll"][data-bs-target=".bd-toc-nav"]');
+    if (scrollSpyBody) {
+        scrollSpyBody.removeAttribute('data-bs-spy');
+        scrollSpyBody.removeAttribute('data-bs-target');
+    }
+}
+
+/**
+ * Make TOC <li> elemenents active;
+ * Add CSS class "active" to all the <nav.bd-toc-nav> > <ul> > <li> elements.
+ */
+function makeTocLiElementsActive() {
+    // The sidebar TOC is <nav> element with class "bd-toc-nav"
+    var navElements = document.querySelectorAll('nav.bd-toc-nav');
+    navElements.forEach(function(navElement) {
+        navElement.childNodes.forEach(function(node) {
+            if (node.tagName === 'UL') {
+                makeDirectLiChildrenActive(node);
+            };
+        });
+    });
+}
+
+
+/**
+ *  Add CSS class "active" to all the direct <li> type children of a node
+ * @param {HTMLElement} node - The node
+ */
+function makeDirectLiChildrenActive(node) {
+    node.childNodes.forEach(function(childNode) {
+        if (childNode.tagName === 'LI') {
+            childNode.classList.add('active');
+        };
+    });
+}
+
+
+/**
+ *  This (1) Disables scroll spy if required (on API Reference page), and "opens"
+ *  the TOC list so that the two first levels of the sidebar TOC are visible.
+ */
+if (shouldDisableScrollSpy()) {
+    disableScrollSpy();
+    makeTocLiElementsActive();
+};

docs/source/api-reference.md

@@ -1,5 +1,6 @@
+<!-- NOTE: If you change the title (API Reference), you must update the code
+in wakepy.js! -->
 # API Reference 
-
 ```{eval-rst}
 
 .. autosummary::

docs/source/conf.py

@@ -22,10 +22,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    # Markdown (MyST) format support for Sphinx
-    "myst_parser",
     # Adds support for NumPy style docstrings for autodoc
+    # Note: numpydoc must be listed before myst_parser in order to make the
+    # NamedTuples fix (https://github.com/numpy/numpydoc/pull/527) work.
     "numpydoc",
+    # Markdown (MyST) format support for Sphinx
+    "myst_parser",
     # Sphinx Design adds some sphinx directives for UI components
     # See: https://sphinx-design.readthedocs.io/
     "sphinx_design",
@@ -63,13 +65,13 @@
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-html_static_path = ["_static"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+html_static_path = ["_static"]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -94,3 +96,7 @@
 # and attributes. If a table of contents is made, Sphinx expects each entry to
 # have a separate page. True by default.
 numpydoc_class_members_toctree = False
+
+
+def setup(app):
+    app.add_js_file("wakepy.js", loading_method="defer")

pyproject.toml

@@ -37,7 +37,9 @@ doc = [
     "sphinx-copybutton~=0.5.2",
     "myst-parser~=2.0.0",
     "sphinx-book-theme~=1.1.0",
-    "numpydoc"
+    # a numpydoc 1.7.0rc0.dev0. This one has https://github.com/numpy/numpydoc/pull/527 merged
+    # At some point: Can use 1.7.0 (which is not available in PyPI at the time of writing)
+    "numpydoc @ git+https://github.com/numpy/numpydoc.git@46f532a824639a97479039fc122533915cdfa10f"
 ]
 dev = [
     "sphinx-autobuild",