Secondary Sidebar TOC active nav element not changing as expected

[fohrloop]

Problem description

I noticed strange behavior with the secondary sidebar TOC highlighter, which shows the "active" part of the page. For some reason, I see that occasionally the "active" part is not highlighted in the sidebar TOC. What I'm referring is this highlight:

Example of problem (gif)

This is perhaps easier to explain with a short video. See that only the A list of functions part is ever "activated" for the highlight.

What I would expect

All the items in the following list would be activated, one by one:

• API Reference
• A list of functions
  • somefunc
• Classes
  • SomeClass
  • AnotherClass
  • ThirdClass

Reproducing the problem

• I've created a repo for this which can be used for reproducing the issue: https://github.com/fohrloop/pydata-sphinx-theme-sidebar-toc-problem
• Just run: sphinx-autobuild docs/source/ docs/build/ -a -E
• The main part is in the index.rst:

API Reference 
---------------

A list of functions
--------------------
.. autofunction:: mypkg.somefunc 

Classes
-------
.. autoclass:: mypkg.SomeClass
    :members:

.. autoclass:: mypkg.AnotherClass
    :members:

.. autoclass:: mypkg.ThirdClass
    :members:

I've not yet found why this happens. Could this be a bug or is it related to some configuration value?

Tested with

pydata-sphinx-theme           0.15.2
Sphinx                        7.2.6

• Downgrading to Sphinx 5.3.0 had no effect

[fohrloop]

Debugging details

(1) The active CSS class is not added correctly

This seems to be related to the `active` CSS class. Here is an example where the `active` is added to `li` and `a` elements at ``` div.bd-sidebar-secondary.bd-toc > nav > ul > li div.bd-sidebar-secondary.bd-toc > nav > ul > li > a ``` (omitted `div > div:nth-child(1)` for clarity)  Note that that `active` class is not added anywhere else. Only at "A list of functions".

(2) The active class is added by Bootstrap 5

Looking at the `src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html`: ``` {# set up with scrollspy to update the toc as we scroll #} {# ref: https://getbootstrap.com/docs/4.0/components/scrollspy/ #} ``` Here is a [link](https://getbootstrap.com/docs/5.2/components/scrollspy/) to Bootstrap 5.2 docs explaining scrollspy.

(3) activate.bs.scrollspy is only triggered once

When I edit `src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js` to contain a console.log ```js function addTOCInteractivity() { window.addEventListener("activate.bs.scrollspy", function () { const navLinks = document.querySelectorAll(".bd-toc-nav a"); console.log(navLinks) // <--- added navLinks.forEach((navLink) => { navLink.parentElement.classList.remove("active"); }); const activeNavLinks = document.querySelectorAll(".bd-toc-nav a.active"); activeNavLinks.forEach((navLink) => { navLink.parentElement.classList.add("active"); }); }); } ``` I can see the event triggering only once when scrolling down the page, at the "A list of functions" section title. The event does not trigger on any other title or when scrolling upwards to "A list of functions" (from bottom of page).

[fohrloop]

It is likely that this is related to how scrollspy works on Bootstrap 5.2. See: https://github.com/twbs/bootstrap/issues (Issue 36431). There are fixes proposed on the page but as I'm not so familiar with front end development it might be better that someone else took a look on it.

[trallard]

Thanks for flagging this @fohrloop. We will look into this and circle back with our findings.

@gabalafou would you be able to look into this?

[Charlie-XIAO]

If the IDs contain dots, then https://github.com/twbs/bootstrap/issues/39248 is perhaps the culprit.

[trallard]

You are right @Charlie-XIAO that seems to be the cause of this behaviour. Since this needs fixing elsewhere, and while the behavior is not ideal, it does not affect the usability of the secondary TOC or similar.

So in that spirit will close the issue and hope this will be resolved upstream.

[CaselIT]

It's still not working correctly. We have adopted this theme in falcon, but while it seem that the active section changes while scrolling the first section is never selected.

Example: https://falcon.readthedocs.io/en/latest/api/util.html Click on Date and Time on the secondary toc or scroll down. The various section open as expect, but the first section URI never does

Other example of the same behaviour, without . in the href: https://falcon.readthedocs.io/en/latest/api/testing.html

[trallard]

Unfortunately, as this is coming directly from bootstrap and the issue remains open and unaddressed, there is not much we can do ATM but wait until this is fixed upstream.

[CaselIT]

shame. it's quite annoying once you notice it