Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Secondary Sidebar TOC active nav element not changing as expected #1724

Closed
fohrloop opened this issue Feb 18, 2024 · 8 comments
Closed

Secondary Sidebar TOC active nav element not changing as expected #1724

fohrloop opened this issue Feb 18, 2024 · 8 comments
Labels
kind: bug Something isn't working
Milestone
Empty milestone.

Comments

@fohrloop
Copy link

fohrloop commented Feb 18, 2024 •
edited
Loading

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:

image

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.

pydata-sphinx-theme-toc-highlight-problem

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

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
Copy link
Author

fohrloop commented Feb 18, 2024 •
edited
Loading

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)

pydata-sphinx-theme-toc-highlight-problem-active

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/ #}
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="{{ default_mode }}">

Here is a link 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

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
Copy link
Author

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
Copy link
Collaborator

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?

@trallard trallard added the kind: bug Something isn't working label Feb 23, 2024
@Charlie-XIAO
Copy link
Contributor

Charlie-XIAO commented Feb 25, 2024 •
edited
Loading

If the IDs contain dots, then twbs/bootstrap#39248 is perhaps the culprit.

@trallard
Copy link
Collaborator

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.

@fohrloop fohrloop mentioned this issue Mar 5, 2024
Merged
fohrloop added a commit to fohrloop/wakepy that referenced this issue Mar 5, 2024
@fohrloop
Docs update: Fix API Reference page (#198)
cc02d95 
Fix the sidebar TOC
===================

The sidebar TOC had a bug. This comes from sphinx-book-theme, which uses
the pydata-sphinx-theme. I filed a bug report in 

pydata/pydata-sphinx-theme#1724

but that was closed as the root cause is likely in the Bootstrap scroll
spy (upstream issue). The bug causes the right side sidebar TOC to not
show fully on the API reference page, "active" <ul> or <li> elements are
shown, and this activation does not work at all on the API Reference
page. 

This could have probably been circumvented in a more elegant way but I
decided to take a shortcut and 

 1. Disable the Bootstrap scroll spy on the API reference page
 2. Activate all nav > ul > li items (second level children) so two
    levels of the TOC is always shown on the API reference page. 

The logic is in the wakepy.js. This can be removed if the issue is fixed
in pydata-sphinx-theme or in sphinx-book-theme.


Remove NamedTuple noise
=======================
The NamedTuples caused noise in the API Reference page. Namely, 
there was extra "Alias for field number X" (X is a number of the field)
items in the docs, for everything that is subclass of NamedTuple.

This fix uses temporarily numpydoc 1.7.0rc0.dev0 directly from 

https://github.com/numpy/numpydoc.git@46f532a824639a97479039fc122533915cdfa10f

When numpydoc 1.7.0 is released, can update pyproject.toml to use that.
@CaselIT
Copy link

CaselIT commented Sep 26, 2024 •
edited
Loading

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
Copy link
Collaborator

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
Copy link

CaselIT commented Sep 27, 2024

shame. it's quite annoying once you notice it

@Carreau Carreau added this to the Empty milestone. milestone Nov 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
kind: bug Something isn't working
Projects
None yet
Milestone
Empty milestone.
Development

No branches or pull requests
5 participants
@Carreau @CaselIT @fohrloop @trallard @Charlie-XIAO