Use a different CSS class to mark TOC levels as visible (#2163)

Fixes #2156.

The underlying issue was that the CSS class `visible` is targeted by
Bootstrap and results in the following rule:

```
visibility: visible !important;
```

which gets applied to the `ul` elements in the secondary sidebar. This
overrides the `visibility: hidden` rule set on the sidebar container
element, making the links focusable via the tab key.

### How to test

1. On a desktop computer, go to a page in Read The Docs preview build.
This page should have a right sidebar visible — i.e., the in-page table
of contents.
2. Click near the bottom of the article and repeatedly press the tab key
to observe how it moves through the links in the secondary sidebar.
3. Zoom the page, or narrow the width of your screen, until the
secondary sidebar disappears.
4. Again, click near the bottom article before the article footer (which
has two links to the previous and next articles)
5. Press the tab key and watch the focus move to those two previous/next
footer links.
6. Keep pressing the tab key and observe that it does not go through any
of the links in the sidebar. (Before this PR, the tab key would take you
through the links in the sidebar, even though those links were not
visible.)

---------

Co-authored-by: Tania Allard <[email protected]>

Author: gabalafou

src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss

@@ -12,7 +12,7 @@ nav.page-toc {
     display: none;
 
     // So we can manually specify a level as visible in the config
-    &.visible {
+    &.pst-show_toc_level {
       display: block;
     }
   }

src/pydata_sphinx_theme/toctree.py

@@ -427,7 +427,7 @@ def add_header_level_recursive(ul, level):
             if ul is None:
                 return
             if level <= (context["theme_show_toc_level"] + 1):
-                ul["class"] = [*ul.get("class", []), "visible"]
+                ul["class"] = [*ul.get("class", []), "pst-show_toc_level"]
             for li in ul("li", recursive=False):
                 li["class"] = [*li.get("class", []), f"toc-h{level}"]
                 add_header_level_recursive(li.find("ul", recursive=False), level + 1)

tests/test_build.py

@@ -52,8 +52,8 @@ def test_toc_visibility(sphinx_build_factory) -> None:
     index_html = sphinx_build.html_tree("index.html")
 
     # The 3rd level headers should be visible, but not the fourth-level
-    assert "visible" in index_html.select(".toc-h2 ul")[0].attrs["class"]
-    assert "visible" not in index_html.select(".toc-h3 ul")[0].attrs["class"]
+    assert "pst-show_toc_level" in index_html.select(".toc-h2 ul")[0].attrs["class"]
+    assert "pst-show_toc_level" not in index_html.select(".toc-h3 ul")[0].attrs["class"]
 
 
 def test_icon_links(sphinx_build_factory, file_regression) -> None: