ENH: Standardize header buttons

Author: choldgraf

.github/workflows/tests.yml

@@ -111,6 +111,7 @@ jobs:
           --exclude 'someurl'
           --exclude 'mailto:docutils-develop'
           --exclude 'pathto\('
+          --exclude 'deepnote.com'
 
     - name: Audit with Lighthouse
       uses: treosh/lighthouse-ci-action@v8

ARCHITECTURE.md

@@ -17,7 +17,10 @@ This folder contains all of the source files for this theme, and most changes to
   This module does things like load in Sphinx's default HTML for the sidebar, and modify it in order to have dropdown nested lists.
   It also inserts several variables into the Jinja template context that are then used in our HTML templates.
 
-`launch.py`
+`header_buttons/`
+: Scripts to generate metadata for buttons in the header. We use [Jinja Macros](https://jinja.palletsprojects.com/en/3.0.x/templates/) (in the `macros/` folder) to generate the HTML for header buttons. The scripts in `header_buttons/` generate the data structure that is used to generate buttons with these macros (in the `header-article.html` template).
+
+`header_buttons/launch.py`
 : Logic to create the correct URLs for our launch buttons. This basically means building the URL for a given launch service in a proper fashion.
 
 The other folders in this section are described in the next few sections.
@@ -31,6 +34,9 @@ These follow the [`sphinx-basic-ng` template structure](https://sphinx-basic-ng.
 
 - `layout.html` inherits from the [pydata sphinx theme](https://pydata-sphinx-theme.readthedocs.io/) and modifies several sections.
 - `theme.conf` contains the Sphinx configuration file for this theme.
+- `macros/` contains HTML templates that define Jinja macros
+- `sections/` contains HTML templates for major sections of the page.
+- `components/` contains HTML templates for smaller, self-contained parts of the page.
 
 ### `/assets/scripts` - JavaScript assets
 

CHANGELOG.md

@@ -160,7 +160,7 @@ This updates to the latest PyData Sphinx Theme, which re-works some of the HTML
 ### New features added
 
 - Added tag for cell-input [#259](https://github.com/executablebooks/sphinx-book-theme/pull/259) ([@AakashGfude](https://github.com/AakashGfude))
-- Add a shadow to topbar, on scroll [#255](https://github.com/executablebooks/sphinx-book-theme/pull/255) ([@pradyunsg](https://github.com/pradyunsg))
+- Add a shadow to header, on scroll [#255](https://github.com/executablebooks/sphinx-book-theme/pull/255) ([@pradyunsg](https://github.com/pradyunsg))
 - Add CSS to center align images with class [#292](https://github.com/executablebooks/sphinx-book-theme/pull/292) ([@DrDrij](https://github.com/DrDrij))
 
 ### Enhancements made

docs/customize/index.md

@@ -26,16 +26,16 @@ The following options are available via `html_theme_options`
   - Branch of the repository for the documentation (e.g., `master`, `main`, `docs`). See [](source-files:repository).
 * - `use_issues_button`
   - bool
-  - Add an button in the topbar with a link to issues for the repository (used in conjunction with `repository_url` and `repository_branch`). See  [](source-files:repository).
+  - Add an button in the header with a link to issues for the repository (used in conjunction with `repository_url` and `repository_branch`). See  [](source-files:repository).
 * - `use_download_button`
   - bool
-  - Add a button in the topbar to download the source file of the page. See [](customize:source-files).
+  - Add a button in the header to download the source file of the page. See [](customize:source-files).
 * - `use_fullscreen_button`
   - bool
-  - Add a button in the topbar to trigger full-screen mode.
+  - Add a button in the header to trigger full-screen mode.
 * - `use_repository_button`
   - bool
-  - Add a button in the topbar that links to the repository of the documentation.See [](source-files:repository).
+  - Add a button in the header that links to the repository of the documentation.See [](source-files:repository).
 * - `launch_buttons`
   - bool
   - Include Binder launch buttons for pages that were built from Jupyter Notebooks. See [](customize:launch).

docs/customize/sidebar-secondary.md

@@ -1,7 +1,7 @@
 # Customize the secondary sidebar
 
 The secondary sidebar contains information about the current page.
-It begins at the top of the page (in the topbar), and extends downwards (by default, from the right side of the page).
+It begins at the top of the page (in the header), and extends downwards (by default, from the right side of the page).
 This page describes ways to control and customize the secondary sidebar.
 
 ## Rename the in-page Table of Contents

docs/tutorials/get-started.md

@@ -59,7 +59,7 @@ html_theme_options = {
 }
 ```
 
-When you build your documentation, your topbar should now include a small GitHub logo that has a link to the repository.
+When you build your documentation, your header should now include a small GitHub logo that has a link to the repository.
 
 
 :::{seealso}

src/sphinx_book_theme/__init__.py

@@ -8,7 +8,8 @@
 from sphinx.locale import get_translation
 from sphinx.util import logging
 
-from .launch import add_hub_urls
+from .header_buttons import prep_header_buttons, add_header_buttons
+from .header_buttons.launch import add_launch_buttons
 
 __version__ = "0.2.0"
 """sphinx-book-theme version"""
@@ -24,8 +25,8 @@ def get_html_theme_path():
     return theme_path
 
 
-def add_to_context(app, pagename, templatename, context, doctree):
-
+def add_metadata_to_page(app, pagename, templatename, context, doctree):
+    """Adds some metadata about the page that we re-use later."""
     # Add the site title to our context so it can be inserted into the navbar
     if not context.get("root_doc"):
         # TODO: Sphinx renamed master to root in 4.x, deprecate when we drop 3.x
@@ -49,43 +50,7 @@ def add_to_context(app, pagename, templatename, context, doctree):
     if app.config.author != "unknown":
         context["author"] = app.config.author
 
-    # Add HTML context variables that the pydata theme uses that we configure elsewhere
-    # For some reason the source_suffix sometimes isn't there even when doctree is
-    if doctree and context.get("page_source_suffix"):
-        config_theme = app.config.html_theme_options
-        repo_url = config_theme.get("repository_url", "")
-        # Only add the edit button if `repository_url` is given
-        if repo_url:
-            branch = config_theme.get("repository_branch")
-            if not branch:
-                # Explicitly check in cae branch is ""
-                branch = "master"
-            relpath = config_theme.get("path_to_docs", "")
-            org, repo = repo_url.strip("/").split("/")[-2:]
-            context.update(
-                {
-                    "github_user": org,
-                    "github_repo": repo,
-                    "github_version": branch,
-                    "doc_path": relpath,
-                }
-            )
-    else:
-        # Disable using the button so we don't get errors
-        context["theme_use_edit_page_button"] = False
-
-    # Make sure the context values are bool
-    btns = [
-        "theme_use_edit_page_button",
-        "theme_use_repository_button",
-        "theme_use_issues_button",
-        "theme_use_download_button",
-        "theme_use_fullscreen_button",
-    ]
-    for key in btns:
-        if key in context:
-            context[key] = _string_or_bool(context[key])
-
+    # Translations
     translation = get_translation(MESSAGE_CATALOG_NAME)
     context["translate"] = translation
     # this is set in the html_theme
@@ -128,15 +93,6 @@ def update_thebe_config(app):
     app.env.config.thebe_config = thebe_config
 
 
-def _string_or_bool(var):
-    if isinstance(var, str):
-        return var.lower() == "true"
-    elif isinstance(var, bool):
-        return var
-    else:
-        return var is None
-
-
 class Margin(Sidebar):
     """Goes in the margin to the right of the page."""
 
@@ -159,16 +115,19 @@ def run(self):
 def setup(app: Sphinx):
     app.connect("builder-inited", update_thebe_config)
 
-    # Configuration for Juypter Book
-    app.connect("html-page-context", add_hub_urls)
-
     # add translations
     theme_dir = get_html_theme_path()
     locale_dir = os.path.join(theme_dir, "static", "locales")
     app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
 
     app.add_html_theme("sphinx_book_theme", theme_dir)
-    app.connect("html-page-context", add_to_context)
+    app.connect("html-page-context", add_metadata_to_page)
+
+    # Header buttons
+    app.connect("html-page-context", prep_header_buttons)
+    app.connect("html-page-context", add_launch_buttons)
+    # Bump priority by 1 so that it runs after the pydata theme sets up the edit URL.
+    app.connect("html-page-context", add_header_buttons, priority=501)
 
     app.add_directive("margin", Margin)
 

src/sphinx_book_theme/_compile_translations.py

@@ -11,11 +11,18 @@
 }
 
 
-def convert_json():
+def convert_json(folder=None):
+    """Convert JSON translations into .mo/.po files for Sphinx.
+
+    folder:
+        the source folder of the JSON translations. This function will put the
+        compiled .mo/.po files in a specific folder relative to this source
+        folder. This parameter is just provided to make testing easier.
+    """
     # Raw translation JSONs that are hand-edited
-    folder = Path(__file__).parent / "assets" / "translations"
+    folder = folder or Path(__file__).parent / "assets" / "translations"
     # Location of compiled static translation assets
-    out_folder = Path(__file__).parent / "theme" / "sphinx_book_theme" / "static"
+    out_folder = folder / ".." / ".." / "theme" / "sphinx_book_theme" / "static"
 
     # compile po
     for path in (folder / "jsons").glob("*.json"):

src/sphinx_book_theme/assets/scripts/index.js

@@ -176,7 +176,10 @@ var initThebeSBT = () => {
  */
 var initTooltips = () => {
   $(document).ready(function () {
-    $('[data-toggle="tooltip"]').tooltip({ trigger: "hover" });
+    $('[data-toggle="tooltip"]').tooltip({
+      trigger: "hover",
+      delay: { show: 500, hide: 100 },
+    });
   });
 };
 

src/sphinx_book_theme/assets/styles/abstracts/_variables.scss

@@ -13,7 +13,7 @@ $grey--medium: #aaa;
 $grey--light: #ccc;
 $non-content-grey: $grey--dark;
 
-$topbar-height: 3em;
+$header-article-height: 3em;
 $leftbar-width-mobile: 75%;
 $leftbar-width-wide: 275px;
 $toc-width-mobile: 75%;
@@ -58,7 +58,7 @@ $border-thin: 1px solid rgba(0, 0, 0, 0.1);
 
   // Variables for this theme
   --sbt-sidebar-font-size: var(--sbt-font-size-small-1);
-  --sbt-topbar-font-size: var(--sbt-font-size-small-1);
+  --sbt-header-article-font-size: var(--sbt-font-size-small-1);
   --sbt-prevnext-font-size: var(--sbt-font-size-small-1);
   --sbt-footer-font-size: var(--sbt-font-size-small-1);
 }

src/sphinx_book_theme/assets/styles/components/_buttons.scss

@@ -1,26 +1,14 @@
 /*********************************************
-* Buttons, mostly for the topbar             *
+* Buttons, mostly for the headers            *
 *********************************************/
-.topbarbtn,
-.topbarbtn--wide {
+/**
+ * Basic button style
+ */
+.headerbtn {
   display: flex;
   align-items: center;
   justify-content: center;
 
-  img {
-    height: 1.15em;
-    padding-right: 6px;
-    margin-left: -5px;
-  }
-
-  // Icon inside the button
-  i {
-    vertical-align: baseline;
-    line-height: 1;
-  }
-}
-
-.topbarbtn {
   background-color: white;
   color: $non-content-grey;
   cursor: pointer;
@@ -35,47 +23,94 @@
     color: black;
     background-color: white;
     box-shadow: none;
+    text-decoration: none;
+  }
+
+  span {
+    display: flex;
+    align-items: center;
+  }
+
+  img,
+  i {
+    margin: auto;
   }
 }
 
-// Buttons with a dropdown list underneath
-div.dropdown-buttons-trigger {
-  div.dropdown-buttons {
-    display: none;
-    position: absolute;
-    max-width: 130px;
-    margin-top: 0;
-    z-index: 1000;
-    transform: translate(-70%);
-
-    // Create extra spacing for these icons since they have
-    i {
-      margin-right: 0.5em;
-    }
+/**
+ * Dropdown groups of buttons
+ */
+.menu-dropdown__trigger:hover + .menu-dropdown__content,
+.menu-dropdown__content:hover {
+  visibility: visible;
+  opacity: 1;
+  transform: translate(-70%); // To achieve a slight shift effect
+}
+
+.menu-dropdown__content {
+  // Hide by default, we'll show on hover
+  position: absolute;
+  visibility: hidden;
+  opacity: 0;
+  transform: translate(-65%);
+  transition: opacity 0.2s ease-out, transform 0.2s ease-out;
 
-    // Links shouldn't have any effect when hovered
-    a:hover {
-      text-decoration: none;
+  // Spacing and position
+  width: 13em;
+  z-index: 1000;
+  border-radius: $box-border-radius;
+  box-shadow: 0px 3px 10px 0px rgba(0, 0, 0, 0.25);
+  padding: 0.5em;
+
+  // Style
+  font-size: 0.9em;
+  background-color: white;
+
+  .headerbtn {
+    justify-content: left;
+
+    // Center the icon in the available white space
+    i,
+    img {
+      margin: auto;
     }
 
-    // Wide topbar buttons have dark backgrounds since they hover over text
-    .topbarbtn--wide {
-      font-size: 1em;
-      padding-top: 0.35rem;
-      padding-bottom: 0.35rem;
-      min-width: 125px !important;
-      border: 1px white solid !important;
-      background-color: $non-content-grey;
-      color: white;
-      border-radius: 0.5em;
+    img {
+      width: 1em;
     }
   }
 
-  &:hover div.dropdown-buttons {
-    display: block;
+  ul {
+    list-style: none;
+    padding-left: 0;
+    margin-bottom: 0;
+  }
+
+  a,
+  button {
+    padding: 0;
+  }
+
+  span {
+    display: flex;
+  }
+
+  span.headerbtn__icon-container {
+    width: 2em;
+  }
+
+  span.headerbtn__text-container {
+    flex-grow: 1;
   }
 }
 
-a.dropdown-buttons i {
-  margin-right: 0.5em;
+/**
+ * In-page table of contents
+ */
+.headerbtn-page-toc {
+  // Hide the button on wide screens since we display the TOC.
+  display: block;
+  @media (min-width: $breakpoint-md) {
+    display: none;
+  }
 }