Standardize template structure in more sections (#1184)

* Standardize template structure in all sections

* Fixing footer behavior

* Update docs/user_guide/layout.rst

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* Remove use of id= as much as possible

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

docs/_templates/test.html

@@ -0,0 +1,2 @@
+{# This is just used for testing in our documentation #}
+<button>TEST</button>

docs/conf.py

@@ -138,7 +138,7 @@
     # "navbar_end": ["theme-switcher", "navbar-icon-links"],
     # "navbar_persistent": ["search-button"],
     # "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
-    # "footer_items": ["copyright", "sphinx-version"],
+    # "footer_start": ["test.html", "test.html"],
     # "secondary_sidebar_items": ["page-toc.html"],  # Remove the source buttons
     "switcher": {
         "json_url": json_url,

docs/user_guide/layout.rst

@@ -10,7 +10,8 @@ Overview of theme layout
 
 Below is a brief overview of the major layout of this theme.
 Take a look at the diagram to understand what the major sections are called.
-You can click on section titles to learn more about them and some basic layout configuration.
+Where you can insert component templates in ``html_theme_options``, we include the variable name ``in inline code``.
+Click on section titles to learn more about them and some basic layout configuration.
 
 .. The directives below generate a grid-like layout that mimics the structure of this theme.
 .. It uses Sphinx Design grids: https://sphinx-design.readthedocs.io/en/latest/grids.html
@@ -52,18 +53,24 @@ You can click on section titles to learn more about them and some basic layout c
 
                 Logo
 
+                ``navbar_start``
+
             .. grid-item::
                 :padding: 2
                 :columns: 6
 
                 Section links
 
+                ``navbar_center``
+
             .. grid-item::
                 :padding: 2
                 :columns: 3
 
                 Components
 
+                ``navbar_end``
+
     .. grid-item::
         :padding: 2
         :outline:
@@ -78,6 +85,10 @@ You can click on section titles to learn more about them and some basic layout c
 
         Links between pages in the active section.
 
+        ``sidebars``
+
+        ``primary_sidebar_end``
+
     .. grid-item::
         :columns: 8
 
@@ -88,7 +99,7 @@ You can click on section titles to learn more about them and some basic layout c
             .. grid-item::
                 :class: content
                 :padding: 2
-                :columns: 8
+                :columns: 6
                 :outline:
 
                 .. button-ref:: layout-article-header
@@ -97,6 +108,9 @@ You can click on section titles to learn more about them and some basic layout c
 
                     Article Header
 
+                ``article_header_start``
+                ``article_header_end``
+
                 **Article Content**
 
                 .. button-ref:: layout-article-footer
@@ -107,7 +121,7 @@ You can click on section titles to learn more about them and some basic layout c
 
             .. grid-item::
                 :padding: 2
-                :columns: 4
+                :columns: 6
                 :outline:
                 :class: sidebar-secondary
 
@@ -119,6 +133,8 @@ You can click on section titles to learn more about them and some basic layout c
 
                 Within-page header links
 
+                ``secondary_sidebar_items``
+
         .. grid::
             :margin: 0
             :gutter: 0
@@ -149,7 +165,8 @@ You can click on section titles to learn more about them and some basic layout c
 
             Footer
 
-        Site-wide links.
+        ``footer_start``
+        ``footer_end``
 
 Horizontal spacing
 ------------------
@@ -425,18 +442,27 @@ Footer
 Located in ``sections/footer.html``.
 
 The footer is just below a page’s main content, and is configured in ``conf.py``
-with ``html_theme_options['footer_items']``.
+with ``html_theme_options['footer_start']`` and ``html_theme_options['footer_end']``.
 
-By default, it has the following templates:
+By default, ``footer_end`` is empty, and ``footer_start`` has the following templates:
 
 .. code-block:: python
 
     html_theme_options = {
       ...
-      "footer_items": ["copyright", "sphinx-version", "theme-version"],
+      "footer_start": ["copyright", "sphinx-version", "theme-version"],
       ...
     }
 
+Within each subsection, components will stack **vertically**.
+If you'd like them to stack **horizontally** use a custom CSS rule like the following:
+
+.. code-block:: css
+
+   .footer-items__start, .footer-items__end {
+     flex-direction: row;
+   }
+
 Change footer display
 ---------------------
 

docs/user_guide/search.rst

@@ -14,7 +14,8 @@ You can also configure some aspects of the search button and search field, descr
 Configure the search field position
 -----------------------------------
 
-The position of the search *button* is controlled by ``search-button`` and by default is included in ``html_theme_options["navbar_persistent"]``; you may move it elsewhere as befits your site's layout, or remove it. You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_items"]``, etc).
+The position of the search *button* is controlled by ``search-button`` and by default is included in ``html_theme_options["navbar_persistent"]``; you may move it elsewhere as befits your site's layout, or remove it.
+You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_start"]``, etc).
 
 For example, if you'd like the search field to be in your side-bar, add it to
 the sidebar templates like so:

docs/user_guide/version-dropdown.rst

@@ -23,7 +23,7 @@ The switcher requires the following configuration steps:
 
 3. Specify where to place the switcher in your page layout. For example, add
    the ``"version-switcher"`` template to one of the layout lists in
-   ``html_theme_options`` (e.g., ``navbar_end``, ``footer_items``, etc).
+   ``html_theme_options`` (e.g., ``navbar_end``, ``footer_start``, etc).
 
 Below is a more in-depth description of each of these configuration steps.
 
@@ -156,7 +156,7 @@ Specify where to display the switcher
 Finally, tell the theme where on your site's pages you want the switcher to
 appear. There are many choices here: you can add ``"version-switcher"`` to one
 of the locations in ``html_theme_options`` (e.g., ``navbar_end``,
-``footer_items``, etc). For example:
+``footer_start``, etc). For example:
 
 .. code:: python
 

src/pydata_sphinx_theme/__init__.py

@@ -67,6 +67,13 @@ def update_config(app):
             "Use `secondary_sidebar_items`."
         )
 
+    # DEPRECATE after 0.14
+    if theme_options.get("footer_items"):
+        theme_options["footer_start"] = theme_options.get("footer_items")
+        logger.warning(
+            "`footer_items` is deprecated. Use `footer_start` or `footer_end` instead."
+        )
+
     # Validate icon links
     if not isinstance(theme_options.get("icon_links", []), list):
         raise ExtensionError(
@@ -205,7 +212,8 @@ def update_and_remove_templates(app, pagename, templatename, context, doctree):
         "theme_navbar_end",
         "theme_article_header_start",
         "theme_article_header_end",
-        "theme_footer_items",
+        "theme_footer_start",
+        "theme_footer_end",
         "theme_secondary_sidebar_items",
         "theme_primary_sidebar_end",
         "sidebars",

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -100,13 +100,13 @@ function addModeListener() {
  */
 function addTOCInteractivity() {
   window.addEventListener("activate.bs.scrollspy", function () {
-    const navLinks = document.querySelectorAll("#bd-toc-nav a");
+    const navLinks = document.querySelectorAll(".bd-toc-nav a");
 
     navLinks.forEach((navLink) => {
       navLink.parentElement.classList.remove("active");
     });
 
-    const activeNavLinks = document.querySelectorAll("#bd-toc-nav a.active");
+    const activeNavLinks = document.querySelectorAll(".bd-toc-nav a.active");
     activeNavLinks.forEach((navLink) => {
       navLink.parentElement.classList.add("active");
     });
@@ -122,7 +122,7 @@ function addTOCInteractivity() {
  */
 function scrollToActive() {
   // If the docs nav doesn't exist, do nothing (e.g., on search page)
-  if (!document.getElementById("bd-docs-nav")) {
+  if (!document.querySelector(".bd-docs-nav")) {
     return;
   }
 
@@ -141,7 +141,7 @@ function scrollToActive() {
     console.log("[PST]: Scrolled sidebar using stored browser position...");
   } else {
     // Otherwise, calculate a position to scroll to based on the lowest `active` link
-    var sidebarNav = document.getElementById("bd-docs-nav");
+    var sidebarNav = document.querySelector(".bd-docs-nav");
     var active_pages = sidebarNav.querySelectorAll(".active");
     if (active_pages.length > 0) {
       // Use the last active page as the offset since it's the page we're on
@@ -305,7 +305,7 @@ function checkPageExistsAndRedirect(event) {
 }
 
 // Populate the version switcher from the JSON config file
-var themeSwitchBtns = document.querySelectorAll("version-switcher__button");
+var themeSwitchBtns = document.querySelectorAll(".version-switcher__button");
 if (themeSwitchBtns.length) {
   fetch(DOCUMENTATION_OPTIONS.theme_switcher_json_url)
     .then((res) => {

src/pydata_sphinx_theme/assets/styles/components/_icon-links.scss

@@ -2,7 +2,25 @@
  * Icon links in the navbar
  */
 
-#navbar-icon-links {
+.navbar-icon-links {
+  display: flex;
+  flex-direction: row;
+  column-gap: 1rem;
+  flex-wrap: wrap;
+
+  // Remove the padding so that we can define it with flexbox gap above
+  li.nav-item a.nav-link {
+    padding-left: 0;
+    padding-right: 0;
+  }
+
+  // Spacing and centering
+  a span {
+    display: flex;
+    align-items: center;
+  }
+
+  // Icons styling
   i {
     &.fa-brands,
     &.fa-regular,
@@ -12,7 +30,7 @@
       font-size: var(--pst-font-size-icon);
     }
 
-    /* Social media buttons */
+    /* Social media buttons hard-code the brand color */
     &.fa-square-twitter:before {
       color: #55acee;
     }
@@ -26,29 +44,9 @@
     }
   }
 
+  // Force images to be icon-sized
   img.icon-link-image {
     height: 1.5em;
     border-radius: 0.2rem;
   }
-
-  li:first-child a {
-    padding-left: 0;
-  }
-
-  a span {
-    display: flex;
-    align-items: center;
-  }
-
-  // inline the element in the navbar as long as they fit and use display block when collapsing
-  // One breakpoint less than $breakpoint-sidebar-primary.
-  // See variables/_layout.scss for more info.
-  @include media-breakpoint-down(lg) {
-    flex-direction: row;
-
-    // Use Bootstrap padding for these nav links to get the spacing right
-    a {
-      padding: 0rem 0.5rem;
-    }
-  }
 }

src/pydata_sphinx_theme/assets/styles/components/_page-toc.scss

@@ -0,0 +1,27 @@
+/**
+ * The list of in-page TOC links
+ */
+.page-toc {
+  .section-nav {
+    padding-left: 0;
+    border-bottom: none;
+
+    ul {
+      padding-left: 1rem;
+    }
+  }
+
+  // override bootstrap settings
+  .nav-link {
+    font-size: var(--pst-sidebar-font-size-mobile);
+    @include media-breakpoint-up($breakpoint-sidebar-secondary) {
+      font-size: var(--pst-sidebar-font-size);
+    }
+  }
+
+  .onthispage {
+    color: var(--pst-color-text-base);
+    font-weight: var(--pst-sidebar-header-font-weight);
+    margin-bottom: 0.5rem;
+  }
+}

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

@@ -36,8 +36,6 @@ div#searchbox {
         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;

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

@@ -36,6 +36,7 @@
 @import "./components/icon-links";
 @import "./components/header/header-logo";
 @import "./components/navbar-links";
+@import "./components/page-toc";
 @import "./components/prev-next";
 @import "./components/search";
 @import "./components/searchbox";

src/pydata_sphinx_theme/assets/styles/sections/_footer.scss

@@ -1,8 +1,27 @@
-footer.bd-footer {
+.bd-footer {
   width: 100%;
   border-top: 1px solid var(--pst-color-border);
-  padding: 10px;
 
+  .bd-footer__inner {
+    display: flex;
+    flex-grow: 1;
+    padding: 1rem;
+    margin: auto;
+  }
+
+  .footer-items__start,
+  .footer-items__end {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    justify-content: center;
+  }
+
+  .footer-items__end {
+    margin-left: auto;
+  }
+
+  // So that paragraphs don't take up extra room
   .footer-item p {
     margin-bottom: 0;
   }

src/pydata_sphinx_theme/assets/styles/sections/_header-article.scss

@@ -1,8 +1,13 @@
 .header-article__inner {
-  min-height: var(--pst-header-article-height);
   display: flex;
   padding: 0 0.5rem;
 
+  // The items define the height so that it disappears if there are no items
+  .header-article-item {
+    min-height: var(--pst-header-article-height);
+    height: var(--pst-header-article-height);
+  }
+
   .header-article-items__start,
   .header-article-items__end {
     display: flex;