Add nav show feature

docs/conf.py

@@ -91,6 +91,7 @@
     ],
     "use_edit_page_button": True,
     "show_toc_level": 1,
+    # "show_nav_level": 2,
     # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     # "navbar_start": ["navbar-logo", "navbar-version"],

docs/user_guide/configuring.rst

@@ -200,6 +200,7 @@ to True:
      "collapse_navigation": True
    }
 
+
 In addition, you can also control how many levels of the navigation are shown
 in the sidebar (with a default of 4):
 
@@ -210,6 +211,19 @@ in the sidebar (with a default of 4):
    }
 
 
+Finally, you can control how many navigation levels are shown when a page is
+loaded. By default, this level is 1, and only top-level pages are shown,
+with drop-boxes to reveal their children. To make their children show up by
+default, you can use the following configuration in ``conf.py``:
+
+.. code:: python
+
+   html_theme_options = {
+     "show_nav_level": 2
+   }
+
+This will make the first two navigations show up by default (AKA, top-level
+pages and their immediate children).
 
 Hiding the previous and next buttons
 ====================================

environment.yml

@@ -6,4 +6,4 @@ dependencies:
 - nodejs>=14,<15  # We should use whatever the LTS is at https://nodejs.org/en/
 - pip
 - pip:
-  - -r docs/requirements.txt
+  - -r docs/requirements.txt

noxfile.py

@@ -31,9 +31,10 @@ def docs_live(session):
 
 
 @nox.session(name="test", venv_backend="conda")
-def tests(session):
+def test(session):
     _install_environment(session, yarn=False)
-    session.run("pytest")
+    session.install(".[test]")
+    session.run("pytest", *session.posargs)
 
 
 def _install_environment(session, yarn=True):

pydata_sphinx_theme/__init__.py

@@ -64,7 +64,7 @@ def update_templates(app, pagename, templatename, context, doctree):
 def add_toctree_functions(app, pagename, templatename, context, doctree):
     """Add functions so Jinja templates can add toctree objects."""
 
-    def generate_nav_html(kind, startdepth=None, **kwargs):
+    def generate_nav_html(kind, startdepth=None, show_nav_level=1, **kwargs):
         """
         Return the navigation link structure in HTML. Arguments are passed
         to Sphinx "toctree" function (context["toctree"] below).
@@ -81,6 +81,12 @@ def generate_nav_html(kind, startdepth=None, **kwargs):
             The level of the toctree at which to start. By default, for
             the navbar uses the normal toctree (`startdepth=0`), and for
             the sidebar starts from the second level (`startdepth=1`).
+        show_nav_level : int
+            The level of the navigation bar to toggle as visible on page load.
+            By default, this level is 1, and only top-level pages are shown,
+            with drop-boxes to reveal children. Increasing `show_nav_level`
+            will show child levels as well.
+
         kwargs: passed to the Sphinx `toctree` template function.
 
         Returns
@@ -127,6 +133,13 @@ def generate_nav_html(kind, startdepth=None, **kwargs):
             # Add icons and labels for collapsible nested sections
             _add_collapse_checkboxes(soup)
 
+            # Open the navbar to the proper depth
+            for ii in range(int(show_nav_level)):
+                for checkbox in soup.select(
+                    f"li.toctree-l{ii} > input.toctree-checkbox"
+                ):
+                    checkbox.attrs["checked"] = None
+
             out = soup.prettify()
 
         elif kind == "raw":

pydata_sphinx_theme/_templates/sidebar-nav-bs.html

@@ -1,6 +1,7 @@
 <nav class="bd-links" id="bd-docs-nav" aria-label="{{ _('Main navigation') }}">
   <div class="bd-toc-item active">
     {{ generate_nav_html("sidebar",
+                         show_nav_level=theme_show_nav_level|int,
                          maxdepth=theme_navigation_depth|int,
                          collapse=theme_collapse_navigation|tobool,
                          includehidden=True,

pydata_sphinx_theme/theme.conf

@@ -24,6 +24,7 @@ search_bar_position = sidebar
 navigation_with_keys = True
 collapse_navigation = False
 navigation_depth = 4
+show_nav_level = 1
 show_toc_level = 1
 navbar_align = content
 navbar_start = navbar-logo.html

tests/test_build.py

@@ -408,3 +408,14 @@ def test_old_google_analytics_id(sphinx_build_factory):
 
     assert "ga" in script_tag.string
     assert "UA-XXXXX" in script_tag.string
+
+
+def test_show_nav_level(sphinx_build_factory):
+    """The navbar items align with the proper part of the page."""
+    confoverrides = {"html_theme_options.show_nav_level": 2}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+
+    # Both the column alignment and the margin should be changed
+    index_html = sphinx_build.html_tree("index.html")
+    for checkbox in index_html.select("li.toctree-l1.has-children > input"):
+        assert "checked" in checkbox.attrs