diff --git a/docs/community/topics.md b/docs/community/topics.md index f275f7688..31cca0564 100644 --- a/docs/community/topics.md +++ b/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"} +} +``` diff --git a/docs/conf.py b/docs/conf.py index 161b15e1a..a79e750b8 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/index.md b/docs/index.md index 166c8936f..c11ff0d9f 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst index 70e7be719..ace3b4ac0 100644 --- a/docs/user_guide/layout.rst +++ b/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 diff --git a/docs/user_guide/page-toc.rst b/docs/user_guide/page-toc.rst index 8a86f5c49..5c3c77f1a 100644 --- a/docs/user_guide/page-toc.rst +++ b/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 `_ at the top of a page. +To remove the Table of Contents, add ``:html_theme.sidebar_secondary.remove:`` to the `file-wide metadata `_ at the top of a page. This will remove the Table of Contents from that page only. diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html index d2dd06714..270d0cb9a 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/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 %}