ENH: Improve sidebar secondary config and logic

docs/community/topics.md

@@ -261,3 +261,24 @@ For more details, see:
 There are a few places where we use `sphinx-design` to generate "galleries" of grids with structured text and images.
 We've created a little Sphinx directive to make it easier to repeat this process in our documentation and to avoid repeating ourselves too much.
 It is located in the `docs/scripts/` folder in a dedicated module, and re-used throughout our documentation.
+
+## Page-level configuration
+
+In some areas we support page-level configuration to control behavior on a per-page basis.
+Try to make this configuration follow the `html_theme_options` structure of our configuration as much as possibl.
+Begin them with `html_theme`, and separate "nested" configuration sections with periods (`.`).
+This is [similar to how the TOML language defines nested configuration](https://toml.io/en/v1.0.0#keys).
+
+For example, to remove the secondary sidebar, we use a page metadata key like this:
+
+```rst
+:html_theme.sidebar_secondary.remove: true
+```
+
+Note how the period naturally separates nested sections, and looks very similar to what we'd expect if we put this in a Python dictionary in `conf.py`:
+
+```python
+html_theme_options = {
+   "sidebar_secondary": {"remove": "true"}
+}
+```

docs/conf.py

@@ -140,7 +140,8 @@
     # "navbar_start": ["navbar-logo"],
     # "navbar_end": ["theme-switcher", "navbar-icon-links"],  # Just for testing, we should use defaults in our docs
     # "left_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
-    # "footer_items": ["copyright", "sphinx-version", ""]
+    # "footer_items": ["copyright", "sphinx-version", ""],
+    # "page_sidebar_items": ["page-toc.html"],  # Remove the source buttons
     "switcher": {
         "json_url": json_url,
         "version_match": version_match,

docs/index.md

@@ -4,7 +4,7 @@ myst:
     "description lang=en": |
       Top-level documentation for pydata-sphinx theme, with links to the rest
       of the site..
-theme_html_remove_secondary_sidebar: true
+html_theme.sidebar_secondary.remove: true
 ---
 
 # The PyData Sphinx Theme

docs/user_guide/layout.rst

@@ -102,7 +102,7 @@ You can click on section titles to learn more about them and some basic layout c
         :padding: 2
         :outline:
         :columns: 2
-        :class: secondary-sidebar
+        :class: sidebar-secondary
 
         .. button-ref:: layout-sidebar-secondary
             :color: primary

docs/user_guide/page-toc.rst

@@ -22,5 +22,5 @@ regardless of what is displayed on the page.
 Remove the Table of Contents
 ----------------------------
 
-To remove the Table of Contents, add ``:theme_html_remove_secondary_sidebar:`` to the `file-wide metadata <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata>`_ at the top of a page.
+To remove the Table of Contents, add ``:html_theme.sidebar_secondary.remove:`` to the `file-wide metadata <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata>`_ at the top of a page.
 This will remove the Table of Contents from that page only.

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -16,8 +16,15 @@
 {% set sidebars = sidebars | reject("in", "sidebar-nav-bs.html") | list %}
 {% endif %}
 
+{# Remove the page-toc from secondary sidebar if there are no links to show #}
+{% if generate_toc_html() | length < 1 %}
+{% set theme_page_sidebar_items = theme_page_sidebar_items | reject("in", "page-toc.html") | list %}
+{% endif %}
+
 {# A flag for whether we include a secondary sidebar based on the page metadata #}
-{% set use_sidebar_secondary = meta is defined and meta is not none and 'theme_html_remove_secondary_sidebar' not in meta %}
+{% set remove_sidebar_secondary = (meta is defined and meta is not none
+                                   and 'html_theme.sidebar_secondary.remove' in meta)
+                                   or not theme_page_sidebar_items %}
 
 {%- block css %}
   <script>
@@ -80,7 +87,7 @@
 
       {# Secondary sidebar #}
       {% block docs_toc %}
-      {% if meta is defined and not (meta is not none and 'theme_html_remove_secondary_sidebar' in meta) %}
+      {% if not remove_sidebar_secondary %}
         <div class="bd-sidebar-secondary bd-toc">
           {% include "sections/sidebar-secondary.html" %}
         </div>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html

@@ -36,7 +36,7 @@
     {%- include "../components/search-button.html" %}
   </div>
 
-  {% if use_sidebar_secondary %}
+  {% if not remove_sidebar_secondary %}
   <label class="sidebar-toggle secondary-toggle" for="__secondary">
       <span class="fas fa-outdent"></span>
   </label>

tests/sites/base/page2.rst

@@ -1,2 +1,4 @@
+:html_theme.sidebar_secondary.remove: true
+
 Page 2
 ======

tests/test_build.py

@@ -74,6 +74,12 @@ def test_build_html(sphinx_build_factory, file_regression):
         sidebar.prettify(), basename="sidebar_subpage", extension=".html"
     )
 
+    # Secondary sidebar should not have in-page TOC if it is empty
+    assert not sphinx_build.html_tree("page1.html").select("div.onthispage")
+
+    # Secondary sidebar should not be present if page-level metadata given
+    assert not sphinx_build.html_tree("page2.html").select("div.bd-sidebar-secondary")
+
 
 def test_toc_visibility(sphinx_build_factory):
     # Test that setting TOC level visibility works as expected