ENH: Implement sticky RHS table of contents with scroll highlighting

[Copilot]

This PR implements the sticky right-hand side (RHS) table of contents feature requested in #315, based on the original work in PR #144. The feature adds an optional sticky positioning behavior to the in-page TOC with automatic section highlighting as users scroll.

Key Features

• Configurable sticky positioning: When enabled via sticky_contents = True, the RHS TOC remains visible while scrolling
• Automatic section highlighting: Current section is highlighted in bold as the user scrolls through the page
• ScrollSpy integration: Uses a lightweight ScrollSpy plugin to track scroll position and update TOC highlighting
• Backward compatible: Feature is disabled by default and doesn't affect existing behavior

Implementation Details

Theme Configuration

Added new sticky_contents option to theme configuration:

html_theme_options = {
    "sticky_contents": True,  # Enable sticky TOC (default: False)
    # ... other options
}

Technical Changes

• HTML Template: Added conditional logic to apply sticky class when feature is enabled
• CSS Styling: Implemented position: sticky; top: 7rem for viewport-relative positioning
• JavaScript: Integrated ScrollSpy plugin for automatic highlighting of current section
• Visual Feedback: Active TOC items are highlighted with bold font-weight

Asset Sizes

• CSS: 50.2KB (minimal increase from new sticky styles)
• JavaScript: 8.8KB (includes ScrollSpy functionality)

Usage

To enable the sticky RHS TOC, add the following to your Sphinx configuration:

html_theme_options = {
    "sticky_contents": True,
}

When enabled, the table of contents will:

1. Remain visible in the right sidebar while scrolling
2. Automatically highlight the current section in bold
3. Maintain proper positioning 7rem from the top of the viewport

The feature enhances navigation for long documents while preserving the existing user experience when disabled.

Fixes #315.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@0358a7c). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #316   +/-   ##
=======================================
  Coverage        ?   45.21%           
=======================================
  Files           ?        2           
  Lines           ?      387           
  Branches        ?        0           
=======================================
  Hits            ?      175           
  Misses          ?      212           
  Partials        ?        0           

Flag	Coverage Δ
pytests	45.21% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mmcky]

Updated for v0.15.1 Compatibility

This PR has been updated to work with the latest main branch (v0.15.1) which includes the modernization refactoring from PR #335.

Changes Made

Adapted to Modular Codebase:

• Created new scrollspy.js module following the modular JavaScript architecture
• Integrated ScrollSpy initialization into the main index.js entry point
• Updated _page.scss module with sticky TOC styles (sticky positioning and active highlighting)
• Maintained all original functionality while conforming to new code organization

Build & Tests:

• ✅ Webpack build successful: scripts/quantecon-book-theme.js now 10.3 KiB
• ✅ All 25 unit tests passing
• ✅ Pre-commit checks passing
• ✅ Compatible with Python 3.12 and 3.13

Feature Summary

The sticky RHS table of contents feature is now fully integrated with the modernized codebase:

1. Configurable: Enable via sticky_contents = True in theme options
2. Auto-highlighting: Current section highlighted in bold as user scrolls
3. Modular: ScrollSpy plugin in dedicated module for maintainability
4. Backward compatible: Disabled by default, no impact on existing projects

Ready for review! 🚀

[github-actions]

🎭 Visual Regression Test Results

 36 passed
 1 flaky
 1 skipped

Details

 38 tests across 1 suite
 53.4 seconds
 a457929

Flaky tests

desktop-chrome › theme.spec.ts › Theme Features › math equation rendering

Skipped tests

mobile-chrome › theme.spec.ts › Theme Features › f-string interpolation styling

[github-actions]

🚀 Deployed on https://693a0bc722087e8c5b7cbd28--hungry-lovelace-7d0512.netlify.app

[mmcky]

Closing in favour of #350