broken reference in API builds

[12rambau]

I wanted to work on the last item preventing us to release the latest version of the theme: #1317

As it's not link to any issue I fail to understand what we are trying to solve here. I checked the current build of our own API and:

• scroll_spy finally work as expected
• clicking on the secondary sidebar links is leading to the one in the page
• search is broken (it doesn't find API items anymore)

@drammock as you have already spend some time working on this could you explain me what is wrong with the links and I'll try to work on it before monday, I really want to show the amazing new collor scheme to the users.

In adition I created a pre-build of one of my repo with the theme and not only it looks amazing, I see no issues with the anchors: https://sepal-ui--876.org.readthedocs.build/en/876/modules/sepal_ui.html

[drammock]

I also have this on my list but I am super swamped this month. If I am correctly understanding the situation:

• #1208 tried to make our theme work more nicely with sphinx-apidoc by changing ids and hrefs on sidebar TOC entries for the documented package's API pages. Specifically, it converts . to _ in id and href.
  • Note that both @choldgraf and I think that the solution should really be an upstream fix
• Meanwhile, #1208 seems to have broken other links
• #1317 attempts to fix what #1208 broke. It is stalled; I did some refactoring of it to make it more DRY and try to understand what it was doing, but the massive searchtools file that was added I haven't even looked at yet.

IMO the best course of action is to revert #1208 and do what we can to help make an upstream fix happen. If you want, we could consider re-merging something like #1208 after cutting the release, but only if it gets some additional work (especially tests) to make sure it's not creating breakages like @tpoint75 discovered. If we do that, it would be helpful if @bheberlein and/or @tpoint75 could help out on the testing side (by helping us craft test(s) that are reflective of their build situations).

[12rambau]

My problem is that I did other documentations recently using other templates like this one with immaterial and there are no issues with the scrollspy in their seconday sidebar. nor does furo in urlib.

My conclusion is maybe it's actually the scrollspy method that should be changed instead.

In any case would you agree to revert changes introduced by #1208 and publish a release and then try to understand what we should change from our javascript side ?

[drammock]

ok after looking a bit more closely I think maybe you're right that the fix should be in scrollspy code. Specifically:

• on kitchen sink page of our stable docs (before Override generation of id & href attributes for API documentation #1208 was merged) scrollspy doesn't work. However, manually adding #urllib.parse.parse_qsl to the URL in the location bar works just fine (scrolls to the correct entry and highlights it).
• Also, clicking on the in-page TOC for that entry works just fine. It seems there is no problem with having the . in the links/anchors per se. It's only scrollspy that can't handle it.

So my conclusion is still: we should revert #1208, then cut a release, then the third step is try to fix #1026 in a different way.