From 6f48aba32381b3dfb65b3b6851e486a591a2a2d3 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 28 Jul 2022 08:18:14 +0200 Subject: [PATCH 1/2] Use nested headers for page config --- docs/community/topics.md | 21 +++++++++++++++++++ docs/index.md | 2 +- docs/user_guide/page-toc.rst | 2 +- .../theme/pydata_sphinx_theme/layout.html | 4 ++-- 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/community/topics.md b/docs/community/topics.md index f275f7688..3a8620e68 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.secondary_sidebar.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 = { + "secondary_sidebar": {"remove": "true"} +} +``` diff --git a/docs/index.md b/docs/index.md index 166c8936f..01fee0cc6 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.secondary_sidebar.remove: true --- # The PyData Sphinx Theme diff --git a/docs/user_guide/page-toc.rst b/docs/user_guide/page-toc.rst index 8a86f5c49..47b2590ea 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.secondary_sidebar.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..2109db193 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -17,7 +17,7 @@ {% 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 use_sidebar_secondary = meta is defined and meta is not none and 'html_theme.secondary_sidebar.remove' not in meta %} {%- block css %}