Clean up sticky TOC implementation and add tests

- Remove debug console.log statements from scrollspy.js
- Add CSS for contents_autoexpand=false mode (hides subsections)
- Add documentation for sticky_contents and contents_autoexpand options
- Add test_sticky_toc unit test for HTML output verification
- Re-enable visual regression tests in CI workflow

Author: mmcky

.github/workflows/ci.yml

@@ -39,46 +39,46 @@ jobs:
           cd lecture-python-programming.myst
           jb build lectures --path-output ./
 
-      # Visual Regression Testing (temporarily disabled for sticky TOC development)
-      # - name: Setup Node.js
-      #   uses: actions/setup-node@v6
-      #   with:
-      #     node-version: '18'
-      #     cache: 'npm'
-      # - name: Install Playwright
-      #   run: |
-      #     npm ci
-      #     npx playwright install --with-deps chromium
-      # - name: Run Visual Regression Tests
-      #   id: visual-tests
-      #   run: npm run test:visual
-      #   continue-on-error: true
-      #   env:
-      #     SITE_PATH: lecture-python-programming.myst/_build/html
-      # - name: Upload Playwright Report
-      #   uses: actions/upload-artifact@v5
-      #   if: always()
-      #   with:
-      #     name: playwright-report
-      #     path: playwright-report/
-      #     retention-days: 30
-      # - name: Upload Test Results (on failure)
-      #   uses: actions/upload-artifact@v5
-      #   if: steps.visual-tests.outcome == 'failure'
-      #   with:
-      #     name: visual-test-diff
-      #     path: test-results/
-      #     retention-days: 30
-      # - name: Post Visual Test Results to PR
-      #   uses: daun/playwright-report-summary@v3
-      #   if: github.event_name == 'pull_request'
-      #   with:
-      #     github-token: ${{ secrets.GITHUB_TOKEN }}
-      #     report-file: playwright-report/results.json
-      #     comment-title: '🎭 Visual Regression Test Results'
-      # - name: Fail if Visual Tests Failed
-      #   if: steps.visual-tests.outcome == 'failure'
-      #   run: exit 1
+      # Visual Regression Testing
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '18'
+          cache: 'npm'
+      - name: Install Playwright
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+      - name: Run Visual Regression Tests
+        id: visual-tests
+        run: npm run test:visual
+        continue-on-error: true
+        env:
+          SITE_PATH: lecture-python-programming.myst/_build/html
+      - name: Upload Playwright Report
+        uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+      - name: Upload Test Results (on failure)
+        uses: actions/upload-artifact@v5
+        if: steps.visual-tests.outcome == 'failure'
+        with:
+          name: visual-test-diff
+          path: test-results/
+          retention-days: 30
+      - name: Post Visual Test Results to PR
+        uses: daun/playwright-report-summary@v3
+        if: github.event_name == 'pull_request'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          report-file: playwright-report/results.json
+          comment-title: '🎭 Visual Regression Test Results'
+      - name: Fail if Visual Tests Failed
+        if: steps.visual-tests.outcome == 'failure'
+        run: exit 1
 
       - name: Preview Deploy to Netlify
         uses: nwtgck/[email protected]

docs/configure.md

@@ -198,6 +198,63 @@ Available Pygments styles include: `default`, `friendly`, `monokai`, `github-dar
 
 When `qetheme_code_style` is `True` (the default), the custom QuantEcon code highlighting is used and the `pygments_style` setting is ignored. When set to `False`, the theme will respect your `pygments_style` configuration.
 
+## Sticky Table of Contents
+
+The theme supports a sticky right-hand-side table of contents (TOC) that remains visible as you scroll through the page. This feature includes scroll spy functionality to highlight the currently visible section, and optional auto-expansion of subsections.
+
+### Enabling Sticky TOC
+
+To enable the sticky table of contents:
+
+```python
+html_theme_options = {
+    ...
+    "sticky_contents": True,
+    ...
+}
+```
+
+For Jupyter Book projects, add to your `_config.yml`:
+
+```yaml
+sphinx:
+  config:
+    html_theme_options:
+      sticky_contents: true
+```
+
+### Features
+
+When enabled, the sticky TOC provides:
+
+- **Fixed positioning**: The TOC stays visible as you scroll
+- **Active section highlighting**: The currently visible section is highlighted in the TOC
+- **Back to top button**: A discrete "Back to top" button appears after scrolling down 300px
+- **Auto-expand subsections**: Subsections automatically expand to show the current hierarchy
+
+### Auto-Expand Subsections
+
+By default, subsections in the TOC automatically expand as you scroll to show the current section hierarchy. This makes it easier to navigate deeply nested content.
+
+To disable auto-expansion while keeping the sticky TOC:
+
+```python
+html_theme_options = {
+    ...
+    "sticky_contents": True,
+    "contents_autoexpand": False,
+    ...
+}
+```
+
+When `contents_autoexpand` is `True` (the default when sticky TOC is enabled), the TOC will:
+- Highlight the active section with bold text (scroll tracking)
+- Expand parent sections to show the active item
+- Expand the active item itself to show its subsections
+- Collapse unrelated sections to reduce visual clutter
+
+When set to `False`, only top-level section names are displayed with bold highlighting to indicate which section the reader is currently in. This provides a cleaner, more compact TOC view while still tracking scroll position.
+
 ## Git-Based Metadata
 
 The theme automatically displays git-based metadata for each page, including the last modified timestamp and an interactive changelog dropdown. This feature requires:

src/quantecon_book_theme/assets/scripts/scrollspy.js

@@ -13,20 +13,16 @@ export function initScrollSpy() {
   // Only initialize if sticky TOC is enabled
   const stickyContainer = document.querySelector(".inner.sticky");
   if (!stickyContainer) {
-    console.log("ScrollSpy: No sticky container found");
     return;
   }
 
   const stickyToc = stickyContainer.querySelector("#bd-toc-nav");
   if (!stickyToc) {
-    console.log("ScrollSpy: No TOC nav found");
     return;
   }
 
   // Check if autoexpand is enabled via data attribute
   const autoExpandEnabled = stickyContainer.dataset.autoexpand === "true";
-  console.log("ScrollSpy initialized, autoExpandEnabled:", autoExpandEnabled);
-  console.log("data-autoexpand attribute:", stickyContainer.dataset.autoexpand);
 
   const tocLinks = stickyToc.querySelectorAll("a");
   if (tocLinks.length === 0) {
@@ -152,34 +148,25 @@ export function initScrollSpy() {
         // Strategy: Expand all ancestors of the active item so it's visible,
         // AND expand the active item itself if it has children (to show its subsections)
 
-        // Debug logging
-        console.log("Active section:", activeSection.id);
-        console.log("Active listItem:", activeSection.listItem);
-
         // 1. First, expand the active item itself if it has children
         // This ensures when you're on "4.2 Function Basics", you see 4.2.1, 4.2.2, etc.
         if (activeSection.listItem.querySelector(":scope > ul")) {
           activeSection.listItem.classList.add("expanded");
-          console.log("Expanded active item (has children)");
         }
 
         // 2. Expand all ancestors from the active item up to the root
         // Start from the parent of the active item's li
         let parentUl = activeSection.listItem.parentElement;
-        console.log("Starting parent traversal from:", parentUl);
         while (parentUl) {
           // parentUl is a <ul>, find its parent <li>
           let parentLi = parentUl.parentElement;
-          console.log("parentLi:", parentLi, "tagName:", parentLi?.tagName);
           if (parentLi && parentLi.tagName === "LI") {
             // This li contains a ul (which contains our active item), so expand it
             parentLi.classList.add("expanded");
-            console.log("Expanded parent li:", parentLi);
             // Move up to the next level
             parentUl = parentLi.parentElement;
           } else {
             // We've reached the top (nav element or similar)
-            console.log("Reached top, breaking");
             break;
           }
         }

src/quantecon_book_theme/assets/styles/_page.scss

@@ -128,6 +128,15 @@ Main page structure and components
       }
     }
 
+    // No auto-expand mode: only show top-level section names
+    // Subsections are permanently hidden, active section is highlighted with bold
+    .inner.sticky[data-autoexpand="false"] &-nav {
+      // Hide all nested subsections permanently
+      ul ul {
+        display: none;
+      }
+    }
+
     // Discrete "Back to top" button for sticky mode
     .back-to-top-btn {
       display: none;

tests/test_build.py

@@ -424,7 +424,69 @@ def test_qetheme_code_style(sphinx_build):
     sphinx_build.clean()
 
 
-def test_git_functions_unit():
+def test_sticky_toc(sphinx_build):
+    """Test that sticky_contents and contents_autoexpand options work correctly."""
+    sphinx_build.copy()
+
+    # Test default behavior - sticky TOC should be disabled
+    sphinx_build.build()
+    index_html = sphinx_build.get("index.html")
+    toc_inner = index_html.find("div", class_="inner")
+    # By default, sticky class should NOT be present
+    assert toc_inner is None or "sticky" not in toc_inner.get("class", [])
+    sphinx_build.clean()
+
+    # Test with sticky_contents enabled
+    cmd = [
+        "-D",
+        "html_theme_options.sticky_contents=True",
+    ]
+    sphinx_build.build(cmd)
+    index_html = sphinx_build.get("index.html")
+    toc_inner = index_html.find("div", class_="inner")
+    # When enabled, sticky class should be present
+    assert toc_inner is not None
+    assert "sticky" in toc_inner.get("class", [])
+    # Default contents_autoexpand should be True
+    assert toc_inner.get("data-autoexpand") == "true"
+    # Back to top button should be present
+    back_to_top = index_html.find("a", class_="back-to-top-btn")
+    assert back_to_top is not None
+    sphinx_build.clean()
+
+    # Test with sticky_contents enabled and contents_autoexpand disabled
+    cmd = [
+        "-D",
+        "html_theme_options.sticky_contents=True",
+        "-D",
+        "html_theme_options.contents_autoexpand=False",
+    ]
+    sphinx_build.build(cmd)
+    index_html = sphinx_build.get("index.html")
+    toc_inner = index_html.find("div", class_="inner")
+    # Sticky class should be present
+    assert toc_inner is not None
+    assert "sticky" in toc_inner.get("class", [])
+    # contents_autoexpand should be false
+    assert toc_inner.get("data-autoexpand") == "false"
+    sphinx_build.clean()
+
+    # Test with string values (theme.conf passes strings)
+    cmd = [
+        "-D",
+        "html_theme_options.sticky_contents=true",
+        "-D",
+        "html_theme_options.contents_autoexpand=false",
+    ]
+    sphinx_build.build(cmd)
+    index_html = sphinx_build.get("index.html")
+    toc_inner = index_html.find("div", class_="inner")
+    # String "true" should enable sticky
+    assert toc_inner is not None
+    assert "sticky" in toc_inner.get("class", [])
+    # String "false" should disable autoexpand
+    assert toc_inner.get("data-autoexpand") == "false"
+    sphinx_build.clean()
     """Unit tests for git helper functions."""
     from quantecon_book_theme import (
         get_git_last_modified,