Fix extra whitespace in sidebars (#1115)

* Fix extra whitespace in sidebars

* Searchbox

* Update src/pydata_sphinx_theme/__init__.py

Co-authored-by: Daniel McCloy <[email protected]>

* make test pass

* Fix template filter to remove empty files

* ABlog in template test

* Move clear search button to primary sidebar

* Move search clear button to top of article

Co-authored-by: Daniel McCloy <[email protected]>

Author: choldgraf

docs/_static/contributors.yaml

@@ -1,24 +1,24 @@
 - header: "@bollwyvl"
   image: https://avatars.githubusercontent.com/u/45380
-  link: https://github.com/bollwyvl
+  website: https://github.com/bollwyvl
 - header: "@jarrodmillman"
   image: https://avatars.githubusercontent.com/u/123428
-  link: https://github.com/jarrodmillman
+  website: https://github.com/jarrodmillman
 - header: "@hoetmaaiers"
   image: https://avatars.githubusercontent.com/u/468045
-  link: https://github.com/hoetmaaiers
+  website: https://github.com/hoetmaaiers
 - header: "@jorisvandenbossche"
   image: https://avatars.githubusercontent.com/u/1020496
-  link: https://github.com/jorisvandenbossche
+  website: https://github.com/jorisvandenbossche
 - header: "@damianavila"
   image: https://avatars.githubusercontent.com/u/1640669
-  link: https://github.com/damianavila
+  website: https://github.com/damianavila
 - header: "@drammock"
   image: https://avatars.githubusercontent.com/u/1810515
-  link: https://github.com/drammock
+  website: https://github.com/drammock
 - header: "@choldgraf"
   image: https://avatars.githubusercontent.com/u/1839645
-  link: https://github.com/choldgraf
+  website: https://github.com/choldgraf
 - header: "@12rambau"
   image: https://avatars.githubusercontent.com/u/12596392
-  link: https://github.com/12rambau
+  website: https://github.com/12rambau

docs/scripts/generate_collaborators_gallery.py

@@ -22,7 +22,7 @@
         {
             "header": f"@{collaborator['login']}",
             "image": f"https://avatars.githubusercontent.com/u/{collaborator['id']}",
-            "link": collaborator["html_url"],
+            "website": collaborator["html_url"],
         }
     )
 

docs/user_guide/source-buttons.rst

@@ -83,13 +83,10 @@ any other context values.
 View Source link
 ================
 
-You can add a button that will direct users to view the source of a page (i.e., the underlying ``reStructuredText`` or ``MyST Markdown`` for the page).
-To do so, add the following extension to your documentation:
+By default, this theme adds a button link to view the source of a page (i.e., the underlying ``reStructuredText`` or ``MyST Markdown`` for the page).
+To disable it, use the following configuration:
+
 
 .. code-block:: python
 
-    extensions = [
-        ...
-        "sphinx.ext.viewcode",
-        ...
-    ]
+    html_show_sourcelink = False

noxfile.py

@@ -1,3 +1,9 @@
+"""Automatically build our documentation or run tests.
+
+Environments are re-used by default. Use the following-pattern to re-install them.
+
+nox -s docs -- -r
+"""
 import nox
 from pathlib import Path
 
@@ -29,6 +35,7 @@ def _should_install(session):
 
 @nox.session
 def compile(session):
+    """Compile the theme's web assets with sphinx-theme-builder."""
     if _should_install(session):
         session.install("-e", ".")
         session.install("sphinx-theme-builder[cli]")
@@ -37,13 +44,15 @@ def compile(session):
 
 @nox.session
 def docs(session):
+    """Build the documentation and place in docs/_build/html."""
     if _should_install(session):
         session.install("-e", ".[doc]")
     session.run("sphinx-build", "-b=html", "docs/", "docs/_build/html")
 
 
 @nox.session(name="docs-live")
 def docs_live(session):
+    """Build the docs with a live server that re-loads as you make changes."""
     if _should_install(session):
         session.install("-e", ".[doc]")
         session.install("sphinx-theme-builder[cli]")
@@ -52,17 +61,15 @@ def docs_live(session):
 
 @nox.session(name="test")
 def test(session):
+    """Run the test suite. Use `-- -r` to re-build the environment."""
     if _should_install(session):
         session.install("-e", ".[test]")
     session.run("pytest", *session.posargs)
 
 
 @nox.session(name="profile")
 def profile(session):
-    """Generate a profile chart with py-spy.
-
-    The chart will be placed at profile.svg and can be viewed in the browser.
-    """
+    """Generate a profile chart with py-spy. The chart will be placed at profile.svg."""
     import shutil as sh
     import tempfile
     from textwrap import dedent

src/pydata_sphinx_theme/__init__.py

@@ -192,7 +192,7 @@ def prepare_html_config(app, pagename, templatename, context, doctree):
     context["theme_version"] = __version__
 
 
-def update_templates(app, pagename, templatename, context, doctree):
+def update_and_remove_templates(app, pagename, templatename, context, doctree):
     """Update template names and assets for page build."""
     # Allow for more flexibility in template names
     template_sections = [
@@ -218,6 +218,20 @@ def update_templates(app, pagename, templatename, context, doctree):
                 if not os.path.splitext(template)[1]:
                     context[section][ii] = template + ".html"
 
+            # If this is the page TOC, check if it is empty and remove it if so
+            def _remove_empty_templates(tname):
+                # These templates take too long to render, so skip them.
+                # They should never be empty anyway.
+                SKIP_EMPTY_TEMPLATE_CHECKS = ["sidebar-nav-bs.html", "navbar-nav.html"]
+                if not any(tname.endswith(temp) for temp in SKIP_EMPTY_TEMPLATE_CHECKS):
+                    # Render the template and see if it is totally empty
+                    rendered = app.builder.templates.render(tname, context)
+                    if len(rendered.strip()) == 0:
+                        return False
+                return True
+
+            context[section] = list(filter(_remove_empty_templates, context[section]))
+
     # Remove a duplicate entry of the theme CSS. This is because it is in both:
     # - theme.conf
     # - manually linked in `webpack-macros.html`
@@ -902,9 +916,12 @@ def _overwrite_pygments_css(app, exception=None):
         # see if user specified a light/dark pygments theme, if not, use the
         # one we set in theme.conf
         style_key = f"pygment_{light_or_dark}_style"
-        theme_name = app.config.html_theme_options.get(
-            style_key, app.builder.globalcontext.get(f"theme_{style_key}")
-        )
+
+        # globalcontext sometimes doesn't exist so this ensures we do not error
+        theme_name = app.config.html_theme_options.get(style_key, None)
+        if theme_name is None and hasattr(app.builder, "globalcontext"):
+            theme_name = app.builder.globalcontext.get(f"theme_{style_key}")
+
         # make sure we can load the style
         if theme_name not in pygments_styles:
             logger.warning(
@@ -1051,8 +1068,8 @@ def setup(app):
     app.connect("builder-inited", update_config)
     app.connect("html-page-context", setup_edit_url)
     app.connect("html-page-context", add_toctree_functions)
-    app.connect("html-page-context", update_templates)
     app.connect("html-page-context", prepare_html_config)
+    app.connect("html-page-context", update_and_remove_templates)
     app.connect("build-finished", _overwrite_pygments_css)
 
     # Include component templates

src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss

@@ -0,0 +1,50 @@
+/**
+ * The 'Hide Search Matches' button.
+ * This only shows up when a person lands on a page after clicking a search result.
+ * Clicking it removes the highlighting of the search term from the page.
+ * We want it to behave like a button.
+ */
+div#searchbox {
+  // Leave `#searchbox` rules empty so that it doesn't show at all when it is empty
+  p.highlight-link {
+    margin: 1rem 0;
+    width: fit-content;
+
+    // A bit more margin on wide screens to mimic article behavior
+    @include media-breakpoint-up($breakpoint-sidebar-secondary) {
+      margin-left: 2rem;
+    }
+
+    // Put outer shadow on this one so that we can darken the link w/ an inner shadow
+    @include box-shadow();
+
+    // Style the button to look like a Sphinx Design button
+    a {
+      border-radius: 0.25rem;
+      font-size: 1.25rem;
+      padding: 0.75rem;
+      background-color: var(--pst-color-primary);
+      // Button text is always white with Sphinx Design buttons
+      color: white;
+
+      // The box shadow is inset so that it darkens the button on hover
+      transition: box-shadow 0.25s ease-out;
+      &:hover {
+        box-shadow: inset 0px 0px 50px 50px rgba(0, 0, 0, 0.25);
+
+        // Remove underline for link
+        text-decoration: none;
+      }
+
+      // add icon via CSS because the link is created by javascript
+      // match padding to .toc-item > i above
+      &:before {
+        content: var(--pst-icon-search-minus);
+        color: unset;
+        font-family: "Font Awesome 6 Free";
+        font-weight: 900;
+        margin-right: 0.5rem;
+      }
+    }
+  }
+}

src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

@@ -37,6 +37,7 @@
 @import "./components/navbar-links";
 @import "./components/prev-next";
 @import "./components/search";
+@import "./components/searchbox";
 @import "./components/switcher-theme";
 @import "./components/switcher-version";
 @import "./components/toc-inpage";

src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss

@@ -53,23 +53,3 @@
     padding-left: 1rem;
   }
 }
-
-// The 'Hide Search Matches' link
-div#searchbox {
-  p.highlight-link {
-    // remove excess margin from p tag
-    margin-bottom: 0px;
-    a {
-      // add icon via CSS because the link is created by javascript
-      // match padding to .toc-item > i above
-      &:before {
-        content: var(--pst-icon-search-minus);
-        color: unset; // make sure it uses the same color as the text
-        font-family: "Font Awesome 6 Free";
-        font-weight: 900;
-        padding-right: 0.5rem;
-        margin-right: 0;
-      }
-    }
-  }
-}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -13,10 +13,6 @@
 {% if sidebar_nav_html | length == 0 %}
   {% 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 == 0 %}
-  {% set theme_secondary_sidebar_items = theme_secondary_sidebar_items | reject("in", "page-toc.html") | list %}
-{% endif %}
 {# A flag for whether we include a secondary sidebar based on the page metadata #}
 {% set remove_sidebar_secondary = (meta is defined and meta is not none
 and 'html_theme.sidebar_secondary.remove' in meta)
@@ -93,6 +89,8 @@
               <div class="bd-header-article">{% include "sections/header-article.html" %}</div>
               {# Article content #}
               {% block docs_body %}
+              {# This is empty and only shows up if text has been highlighted by the URL #}
+                {% include "components/searchbox.html" %}
                 <article class="bd-article" role="main">
                   {% block body %}{% endblock %}
                 </article>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -35,7 +35,7 @@ navbar_persistent = search-button.html
 header_links_before_dropdown = 5
 primary_sidebar_end = sidebar-ethical-ads.html
 footer_items = copyright.html, theme-version.html, sphinx-version.html
-secondary_sidebar_items = page-toc.html, searchbox.html, edit-this-page.html, sourcelink.html
+secondary_sidebar_items = page-toc.html, edit-this-page.html, sourcelink.html
 switcher =
 check_switcher = True
 pygment_light_style = a11y-high-contrast-light

tests/sites/deprecated/conf.py

@@ -24,7 +24,6 @@
     "logo_text": "DOCS",
     "page_sidebar_items": [
         "page-toc.html",
-        "searchbox.html",
         "edit-this-page.html",
         "sourcelink.html",
     ],

tests/test_build.py

@@ -541,7 +541,7 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_url):
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides)
 
     if edit_url is None:
-        with pytest.raises(sphinx.errors.ThemeError):
+        with pytest.raises(sphinx.errors.ExtensionError):
             sphinx_build.build()
         return
 
@@ -765,6 +765,8 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
     file_regression.check(navbar.prettify(), basename="navbar_ix", extension=".html")
 
     # Sidebar subpage
+    # This re-uses the same HTML template used above (w/o deprecated config)
+    # because they should still be the same.
     sidebar = subpage_html.select(".bd-sidebar")[0]
     file_regression.check(
         sidebar.prettify(), basename="sidebar_subpage", extension=".html"
@@ -783,3 +785,13 @@ def test_ablog(sphinx_build_factory):
     confoverrides = {"extensions": ["ablog"]}
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
     assert sphinx_build.app.config.fontawesome_included is True
+
+
+def test_empty_templates(sphinx_build_factory):
+    """If a template is empty (e.g., via a config), it should be removed."""
+    # When configured to be gone, the template should be removed w/ its parent.
+    # ABlog needs to be added so we can test that template rendering works w/ it.
+    confoverrides = {"html_show_sourcelink": False, "extensions": ["ablog"]}
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    toc_items = sphinx_build.html_tree("page1.html").select(".toc-item")
+    assert not any(ii.select(".tocsection.sourcelink") for ii in toc_items)

tests/test_build/sidebar_subpage.html

@@ -81,8 +81,6 @@
   </div>
  </div>
  <div class="sidebar-end-items sidebar-primary__section">
-  <div class="sidebar-end-items__item">
-  </div>
  </div>
  <div id="rtd-footer-container">
  </div>