Merge branch 'main' into fix-scrollable-notebook-outputs

.github/workflows/tests.yml

@@ -22,6 +22,7 @@ on:
 
 jobs:
   lint:
+    timeout-minutes: 3
     strategy:
       matrix:
         os: [ubuntu-latest]
@@ -39,6 +40,7 @@ jobs:
 
   # run our test suite on various combinations of OS / Python / Sphinx version
   run-pytest:
+    timeout-minutes: 10
     needs: [lint]
     strategy:
       fail-fast: false
@@ -152,6 +154,7 @@ jobs:
 
   # Build our site on the 3 major OSes and check for Sphinx warnings
   build-site:
+    timeout-minutes: 15
     needs: [lint]
     strategy:
       fail-fast: false

.pre-commit-config.yaml

@@ -52,3 +52,8 @@ repos:
     rev: "0.7.1"
     hooks:
       - id: nbstripout
+
+  - repo: https://github.com/mondeja/pre-commit-po-hooks
+    rev: v1.7.3
+    hooks:
+      - id: remove-metadata

docs/user_guide/announcements.rst

@@ -44,12 +44,20 @@ For example, the following configuration tells the theme to load the ``custom-te
 Update or remove announcement banner
 ------------------------------------
 
-To update or remove the announcement banner, you can change the value of
-``html_theme_options["announcement"]`` in your ``conf.py`` or you can edit the
-contents of the ``custom-template.html`` file directly. For example, if you have a
-temporary announcement that you want to remove without rebuilding your
-documentation pages, you can use an empty ``custom-template.html`` file and the
-banner will be hidden.
+If you set ``html_theme_options["announcement"]`` to plain text or HTML, then to
+update the announcement banner you need to modify this string and rebuild your
+documentation pages. To remove the announcement banner, set this value to an
+empty string and rebuild your documentation pages.
+
+If you set ``html_theme_options["announcement"]`` to a URL string (starts with
+``http``), then you can edit the file at that URL to update the announcement
+banner. Saving an empty file at that URL will remove the announcement banner.
+That's the main advantage of using a URL--you can change the announcement banner
+without rebuilding and redeploying all of your documentation pages. For example,
+if you point the announcement to the URL of a file in your repo, as we do on
+this documentation site (see previous section), then you can edit, save and push
+your changes to just that file (empty file = remove announcement) without
+rebuilding and redeploying all your docs.
 
 .. _version-warning-banners:
 

src/pydata_sphinx_theme/__init__.py

@@ -12,7 +12,7 @@
 from sphinx.builders.dirhtml import DirectoryHTMLBuilder
 from sphinx.errors import ExtensionError
 
-from . import edit_this_page, logo, pygment, short_link, toctree, translator, utils
+from . import edit_this_page, logo, pygments, short_link, toctree, translator, utils
 
 __version__ = "0.15.3"
 
@@ -26,6 +26,16 @@ def update_config(app):
     theme_options = utils.get_theme_options_dict(app)
     warning = partial(utils.maybe_warn, app)
 
+    # TODO: DEPRECATE after v1.0
+    themes = ["light", "dark"]
+    for theme in themes:
+        if style := theme_options.get(f"pygment_{theme}_style"):
+            theme_options[f"pygments_{theme}_style"] = style
+            warning(
+                f'The parameter "pygment_{theme}_style" was renamed to '
+                f'"pygments_{theme}_style" (note the "s" on "pygments").'
+            )
+
     # Validate icon links
     if not isinstance(theme_options.get("icon_links", []), list):
         raise ExtensionError(
@@ -269,7 +279,7 @@ def setup(app: Sphinx) -> Dict[str, str]:
     app.connect("html-page-context", update_and_remove_templates)
     app.connect("html-page-context", logo.setup_logo_path)
     app.connect("html-page-context", utils.set_secondary_sidebar_items)
-    app.connect("build-finished", pygment.overwrite_pygments_css)
+    app.connect("build-finished", pygments.overwrite_pygments_css)
     app.connect("build-finished", logo.copy_logo_images)
 
     # https://www.sphinx-doc.org/en/master/extdev/i18n.html#extension-internationalization-i18n-and-localization-l10n-using-i18n-api

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

@@ -488,16 +488,13 @@ function showVersionWarningBanner(data) {
     return;
   }
   // now construct the warning banner
-  var outer = document.createElement("aside");
-  // TODO: add to translatable strings
-  outer.setAttribute("aria-label", "Version warning");
+  const banner = document.querySelector(".bd-header-version-warning");
   const middle = document.createElement("div");
   const inner = document.createElement("div");
   const bold = document.createElement("strong");
   const button = document.createElement("a");
   // these classes exist since pydata-sphinx-theme v0.10.0
   // the init class is used for animation
-  outer.classList = "bd-header-version-warning container-fluid init";
   middle.classList = "bd-header-announcement__content";
   inner.classList = "sidebar-message";
   button.classList =
@@ -522,35 +519,12 @@ function showVersionWarningBanner(data) {
   } else {
     bold.innerText = `version ${version}`;
   }
-  outer.appendChild(middle);
+  banner.appendChild(middle);
   middle.appendChild(inner);
   inner.appendChild(bold);
   inner.appendChild(document.createTextNode("."));
   inner.appendChild(button);
-  const skipLink = document.getElementById("pst-skip-link");
-  skipLink.after(outer);
-  // At least 3rem height
-  const autoHeight = Math.max(
-    outer.offsetHeight,
-    3 * parseFloat(getComputedStyle(document.documentElement).fontSize),
-  );
-  // Set height and vertical padding to 0 to prepare the height transition
-  outer.style.setProperty("height", 0);
-  outer.style.setProperty("padding-top", 0);
-  outer.style.setProperty("padding-bottom", 0);
-  outer.classList.remove("init");
-  // Set height to the computed height with a small timeout to activate the transition
-  setTimeout(() => {
-    outer.style.setProperty("height", `${autoHeight}px`);
-    // Wait for a bit more than 300ms (the transition duration) then remove the
-    // forcefully set styles and let CSS take over
-    setTimeout(() => {
-      outer.style.removeProperty("padding-top");
-      outer.style.removeProperty("padding-bottom");
-      outer.style.removeProperty("height");
-      outer.style.setProperty("min-height", "3rem");
-    }, 320);
-  }, 10);
+  banner.classList.remove("d-none");
 }
 
 /*******************************************************************************
@@ -584,27 +558,29 @@ function initRTDObserver() {
   observer.observe(document.body, config);
 }
 
-// fetch the JSON version data (only once), then use it to populate the version
-// switcher and maybe show the version warning bar
-var versionSwitcherBtns = document.querySelectorAll(
-  ".version-switcher__button",
-);
-const hasSwitcherMenu = versionSwitcherBtns.length > 0;
-const hasVersionsJSON = DOCUMENTATION_OPTIONS.hasOwnProperty(
-  "theme_switcher_json_url",
-);
-const wantsWarningBanner = DOCUMENTATION_OPTIONS.show_version_warning_banner;
-
-if (hasVersionsJSON && (hasSwitcherMenu || wantsWarningBanner)) {
-  const data = await fetchVersionSwitcherJSON(
-    DOCUMENTATION_OPTIONS.theme_switcher_json_url,
+async function fetchAndUseVersions() {
+  // fetch the JSON version data (only once), then use it to populate the version
+  // switcher and maybe show the version warning bar
+  var versionSwitcherBtns = document.querySelectorAll(
+    ".version-switcher__button",
+  );
+  const hasSwitcherMenu = versionSwitcherBtns.length > 0;
+  const hasVersionsJSON = DOCUMENTATION_OPTIONS.hasOwnProperty(
+    "theme_switcher_json_url",
   );
-  // TODO: remove the `if(data)` once the `return null` is fixed within fetchVersionSwitcherJSON.
-  // We don't really want the switcher and warning bar to silently not work.
-  if (data) {
-    populateVersionSwitcher(data, versionSwitcherBtns);
-    if (wantsWarningBanner) {
-      showVersionWarningBanner(data);
+  const wantsWarningBanner = DOCUMENTATION_OPTIONS.show_version_warning_banner;
+
+  if (hasVersionsJSON && (hasSwitcherMenu || wantsWarningBanner)) {
+    const data = await fetchVersionSwitcherJSON(
+      DOCUMENTATION_OPTIONS.theme_switcher_json_url,
+    );
+    // TODO: remove the `if(data)` once the `return null` is fixed within fetchVersionSwitcherJSON.
+    // We don't really want the switcher and warning bar to silently not work.
+    if (data) {
+      populateVersionSwitcher(data, versionSwitcherBtns);
+      if (wantsWarningBanner) {
+        showVersionWarningBanner(data);
+      }
     }
   }
 }
@@ -751,9 +727,70 @@ if (document.readyState === "complete") {
   window.addEventListener("load", addTabStopsToScrollableElements);
 }
 
+/*******************************************************************************
+ * Announcement banner - fetch and load remote HTML
+ */
+async function setupAnnouncementBanner() {
+  const banner = document.querySelector(".bd-header-announcement");
+  const { pstAnnouncementUrl } = banner.dataset;
+
+  if (!pstAnnouncementUrl) {
+    return;
+  }
+
+  try {
+    const response = await fetch(pstAnnouncementUrl);
+    if (!response.ok) {
+      throw new Error(
+        `[PST]: HTTP response status not ok: ${response.status} ${response.statusText}`,
+      );
+    }
+    const data = await response.text();
+    if (data.length === 0) {
+      console.log(`[PST]: Empty announcement at: ${pstAnnouncementUrl}`);
+      return;
+    }
+    banner.innerHTML = `<div class="bd-header-announcement__content">${data}</div>`;
+    banner.classList.remove("d-none");
+  } catch (_error) {
+    console.log(`[PST]: Failed to load announcement at: ${pstAnnouncementUrl}`);
+    console.error(_error);
+  }
+}
+
+/*******************************************************************************
+ * Reveal (and animate) the banners (version warning, announcement) together
+ */
+async function fetchRevealBannersTogether() {
+  // Wait until finished fetching and loading banners
+  await Promise.allSettled([fetchAndUseVersions(), setupAnnouncementBanner()]);
+
+  // The revealer element should have CSS rules that set height to 0, overflow
+  // to hidden, and an animation transition on the height (unless the user has
+  // turned off animations)
+  const revealer = document.querySelector(".pst-async-banner-revealer");
+
+  // Remove the d-none (display-none) class to calculate the children heights.
+  revealer.classList.remove("d-none");
+
+  // Add together the heights of the element's children
+  const height = Array.from(revealer.children).reduce(
+    (height, el) => height + el.offsetHeight,
+    0,
+  );
+
+  // Use the calculated height to give the revealer a non-zero height (if
+  // animations allowed, the height change will animate)
+  revealer.style.setProperty("height", `${height}px`);
+}
+
 /*******************************************************************************
  * Call functions after document loading.
  */
+
+// Call this one first to kick off the network request for the version warning
+// and announcement banner data as early as possible.
+documentReady(fetchRevealBannersTogether);
 documentReady(addModeListener);
 documentReady(scrollToActive);
 documentReady(addTOCInteractivity);

src/pydata_sphinx_theme/assets/styles/content/_tables.scss

@@ -55,3 +55,9 @@ td {
     --pst-color-text-base
   ); // ensure text and bullets are visible
 }
+
+.pst-scrollable-table-container {
+  // Put a scrollbar just below tables that are too wide to fit within the main
+  // column
+  overflow-x: auto;
+}

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

@@ -1,34 +1,38 @@
+.pst-async-banner-revealer {
+  // Setting height to 0 and overflow to hidden allows us to add up the heights
+  // of this element's children before revealing them.
+  height: 0;
+  overflow: hidden;
+
+  // Height to be set by JavaScript, which should trigger the following
+  // transition rule (unless the user has set their system to reduce motion).
+  transition: height 300ms ease-in-out;
+  @media (prefers-reduced-motion) {
+    transition: none;
+  }
+}
+
 .bd-header-version-warning,
 .bd-header-announcement {
+  min-height: 3rem;
   width: 100%;
   display: flex;
   position: relative;
   align-items: center;
   justify-content: center;
   text-align: center;
-  transition: height 300ms ease-in-out;
-  overflow-y: hidden;
   padding: 0.5rem 12.5%; // Horizontal padding so the width is 75%
   // One breakpoint less than $breakpoint-sidebar-primary. See variables/_layout.scss for more info.
   @include media-breakpoint-down(lg) {
     // Announcements can take a bit more width on mobile
     padding: 0.5rem 2%;
   }
 
-  &.init {
-    position: fixed;
-    visibility: hidden;
-  }
-
   p {
     font-weight: bold;
     margin: 0;
   }
 
-  &:empty {
-    display: none;
-  }
-
   // Ensure there is enough contrast against the background
   a {
     color: var(--pst-color-inline-code-links);

src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po

@@ -8,19 +8,6 @@
 # Cristhian Rivera, 2024
 msgid ""
 msgstr ""
-"Project-Id-Version: PROJECT VERSION\n"
-"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-04-29 13:43+0200\n"
-"PO-Revision-Date: 2023-04-14 14:57+0000\n"
-"Last-Translator: Cristhian Rivera, 2024\n"
-"Language: ca\n"
-"Language-Team: Catalan "
-"(https://app.transifex.com/12rambau/teams/166811/ca/)\n"
-"Plural-Forms: nplurals=2; plural=(n != 1);\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=utf-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 2.13.0\n"
 
 #: docs/conf.py:94
 msgid "Click to expand"
@@ -156,7 +143,11 @@ msgstr ""
 "theme.readthedocs.io/en/stable/index.html\">Tema PyData Sphinx</a> "
 "%(theme_version)s."
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html:1
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html:4
+msgid "Version warning"
+msgstr ""
+
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html:6
 msgid "Announcement"
 msgstr ""
 
@@ -179,4 +170,3 @@ msgstr "Navegació del lloc"
 
 #~ msgid "Twitter"
 #~ msgstr "Twitter"
-