ENH: add show_toc_level config option to choose visible levels of toc (#256)

Author: choldgraf

docs/conf.py

@@ -65,6 +65,7 @@
     "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme",
     "twitter_url": "https://twitter.com/pandas_dev",
     "use_edit_page_button": True,
+    "show_toc_level": 1,
 }
 
 html_context = {

docs/user_guide/configuring.rst

@@ -150,3 +150,22 @@ use the following configuration:
    html_theme_options = {
      "navigation_with_keys": False
    }
+
+
+Show more levels of the in-page TOC by default
+==============================================
+
+Normally only the 2nd-level headers of a page are show in the right
+table of contents, and deeper levels are only shown when they are part
+of an active section (when it is scrolled on screen).
+
+You can show deeper levels by default by using the following configuration, indicating how many levels should be displayed:
+
+.. code-block:: python
+
+   html_theme_options = {
+     "show_toc_level": 2
+   }
+
+All headings up to and including the level specified will now be shown
+regardless of what is displayed on the page.

pydata_sphinx_theme/__init__.py

@@ -173,6 +173,9 @@ def get_edit_url():
 
     context["get_edit_url"] = get_edit_url
 
+    # Ensure that the max TOC level is an integer
+    context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))
+
 
 # -----------------------------------------------------------------------------
 

pydata_sphinx_theme/docs-toc.html

@@ -12,7 +12,7 @@
         <li class="nav-item toc-entry toc-h{{ loop.depth + 1 }}">
             <a href="{{ item.url }}" class="nav-link">{{ item.title }}</a>
         {%- if item.children -%}
-            <ul class="nav section-nav flex-column">
+            <ul class="nav section-nav flex-column{% if (loop.depth + 1) <= theme_show_toc_level %} visible{% endif %}">
                 {{ loop(item.children) }}
             </ul>
         {%- endif %}

pydata_sphinx_theme/static/css/index.689d8a1e63c34b0b2966dc009a5ecd08.css renamed to pydata_sphinx_theme/static/css/index.73d71520a4ca3b99cfee5594769eaaae.css

@@ -16,13 +16,13 @@
 {% endmacro %}
 
 {% macro head_pre_bootstrap() %}
-  <link rel="stylesheet" href="{{ pathto('_static/css/index.689d8a1e63c34b0b2966dc009a5ecd08.css', 1) }}">
+  <link rel="stylesheet" href="{{ pathto('_static/css/index.73d71520a4ca3b99cfee5594769eaaae.css', 1) }}">
 {% endmacro %}
 
 {% macro head_js_preload() %}
-  <link rel="preload" as="script" href="{{ pathto('_static/js/index.0c807b2b8646875702ce.js', 1) }}">
+  <link rel="preload" as="script" href="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}">
 {% endmacro %}
 
 {% macro body_post() %}
-  <script src="{{ pathto('_static/js/index.0c807b2b8646875702ce.js', 1) }}"></script>
+  <script src="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}"></script>
 {% endmacro %}

pydata_sphinx_theme/static/js/index.0c807b2b8646875702ce.js renamed to pydata_sphinx_theme/static/js/index.3da636dd464baa7582d2.js

@@ -13,4 +13,5 @@ google_analytics_id =
 show_prev_next = True
 search_bar_text = Search the docs ...
 search_bar_position = sidebar
-navigation_with_keys = True
+navigation_with_keys = True
+show_toc_level = 1

pydata_sphinx_theme/static/webpack-macros.html

@@ -350,8 +350,14 @@ table.field-list {
 .bd-toc .nav {
   .nav {
     display: none;
+
+    // So we can manually specify a level as visible in the config
+    &.visible {
+      display: block;
+    }
   }
 
+
   > .active > ul {
     display: block;
   }

pydata_sphinx_theme/theme.conf

@@ -8,3 +8,12 @@ Index ``with code`` in title
    page1
    page2
    section1/index
+
+A header
+--------
+
+A sub-header
+~~~~~~~~~~~~
+
+A sub-sub-header
+````````````````

src/scss/index.scss

@@ -68,3 +68,15 @@ def test_build_book(file_regression, sphinx_build):
     )
 
     sphinx_build.clean()
+
+
+def test_toc_visibility(file_regression, sphinx_build):
+    sphinx_build.copy()
+
+    # Test that setting TOC level visibility works as expected
+    sphinx_build.build(["-D", "html_theme_options.show_toc_level=2"])
+    index_html = sphinx_build.get("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"]