diff --git a/docs/community/bootstrap.rst b/docs/community/bootstrap.rst new file mode 100644 index 000000000..58b548a10 --- /dev/null +++ b/docs/community/bootstrap.rst @@ -0,0 +1,60 @@ +Upgrade to bootstrap 5 +====================== + +Since *v0.13*, ``pydata-sphinx-theme`` has moved from Bootstrap 4 to `Bootstrap 5 `_. +This documentation will guide you through the changes we made and how you could follow the same steps in your existing documentation. + +Dropping **JQuery** +------------------- + +Bootstrap Dropped its **JQuery** dependency and rewrote plugins to be in regular JavaScript. +Sphinx *v6* will do the same (https://github.com/sphinx-doc/sphinx/issues/10070). +As a consequence, we also rewrote all our javascript to only use vanilla **JavaScript**. +Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite it or specifically import **JQuery**. + +Breaking changes +---------------- + +‼️ Relevant for those using a ``custom.css`` and/or a ``custom.js`` file! + +Bootstrap changed a number of CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed. + +All of the changes from *v4* to *v5* are `listed in their documentation `_. +Below list the ones that had consequences on ``pydata-sphinx-theme`` components. + +Sass +^^^^ + +- Media query mixins parameters have changed for a more logical approach. + + - ``media-breakpoint-down()`` uses the breakpoint itself instead of the next breakpoint (e.g., ``media-breakpoint-down(lg)`` instead of ``media-breakpoint-down(md)`` targets viewports smaller than lg). + - Similarly, the second parameter in ``media-breakpoint-between()`` also uses the breakpoint itself instead of the next breakpoint (e.g., ``media-between(sm, lg)`` instead of ``media-breakpoint-between(sm, md)`` targets viewports between sm and lg). + +- ``box-shadow`` mixins now allow ``null`` values and drop ``none`` from multiple arguments. + +Content, Reboot, etc +^^^^^^^^^^^^^^^^^^^^ + +- Nested tables do not inherit styles anymore. + +- ``.thead-light`` and ``.thead-dark`` are dropped in favor of the ``.table-*`` variant classes which can be used for all table elements (``thead``, ``tbody``, ``tfoot``, ``tr``, ``th`` and ``td``). + +- Dropped ``.text-justify`` class. See https://github.com/twbs/bootstrap/pull/29793 + +Utilities +^^^^^^^^^ + +- Renamed several utilities to use logical property names instead of directional names with the addition of RTL support: + + - Renamed ``.left-*`` and ``.right-*`` to ``.start-*`` and ``.end-*``. + - Renamed ``.float-left`` and ``.float-right`` to ``.float-start`` and ``.float-end``. + - Renamed ``.border-left`` and ``.border-right`` to ``.border-start`` and ``.border-end``. + - Renamed ``.rounded-left`` and ``.rounded-right`` to ``.rounded-start`` and ``.rounded-end``. + - Renamed ``.ml-*`` and ``.mr-*`` to ``.ms-*`` and ``.me-*``. + - Renamed ``.pl-*`` and ``.pr-*`` to ``.ps-*`` and ``.pe-*``. + - Renamed ``.text-left`` and ``.text-right`` to ``.text-start`` and ``.text-end``. + +JavaScript +^^^^^^^^^^ + +- Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``. diff --git a/docs/community/index.md b/docs/community/index.md index 33deabd29..f704e61ba 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -16,7 +16,7 @@ setup structure topics manual - +bootstrap ``` ```{toctree} diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst index c0239cddc..90144d3a3 100644 --- a/docs/user_guide/web-components.rst +++ b/docs/user_guide/web-components.rst @@ -105,7 +105,7 @@ Cards .. grid-item-card:: A card with a dropdown menu - .. dropdown:: :fa:`eye,mr-1` third card + .. dropdown:: :fa:`eye me-1` third card Hidden content diff --git a/package-lock.json b/package-lock.json index 016df0408..b57a2e5bd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -140,6 +140,11 @@ } } }, + "@popperjs/core": { + "version": "2.11.6", + "resolved": "https://registry.npmjs.org/@popperjs/core/-/core-2.11.6.tgz", + "integrity": "sha512-50/17A98tWUfQ176raKiOGXuYpLyyVMkxxG6oylzL3BPOlA6ADGdK7EYunSa4I064xerltq9TGXs8HmOk5E+vw==" + }, "@tootallnate/once": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-1.1.2.tgz", @@ -1108,9 +1113,9 @@ "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==" }, "bootstrap": { - "version": "4.6.1", - "resolved": "https://registry.npmjs.org/bootstrap/-/bootstrap-4.6.1.tgz", - "integrity": "sha512-0dj+VgI9Ecom+rvvpNZ4MUZJz8dcX7WCX+eTID9+/8HgOkv3dsRzi8BGeZJCQU6flWQVYxwTQnEZFrmJSEO7og==" + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/bootstrap/-/bootstrap-5.2.2.tgz", + "integrity": "sha512-dEtzMTV71n6Fhmbg4fYJzQsw1N29hJKO1js5ackCgIpDcGid2ETMGC6zwSYw09v05Y+oRdQ9loC54zB1La3hHQ==" }, "brace-expansion": { "version": "1.1.11", @@ -4250,11 +4255,6 @@ "integrity": "sha512-Yljz7ffyPbrLpLngrMtZ7NduUgVvi6wG9RJ9IUcyCd59YQ911PBJphODUcbOVbqYfxe1wuYf/LJ8PauMRwsM/g==", "dev": true }, - "jquery": { - "version": "3.5.1", - "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz", - "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg==" - }, "js-base64": { "version": "2.6.4", "resolved": "https://registry.npmjs.org/js-base64/-/js-base64-2.6.4.tgz", @@ -5688,11 +5688,6 @@ "find-up": "^3.0.0" } }, - "popper.js": { - "version": "1.16.1", - "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.16.1.tgz", - "integrity": "sha512-Wb4p1J4zyFTbM+u6WuO4XstYx4Ky9Cewe4DWrel7B0w6VVICvPwdOpotjzcf6eD8TsckVnIMNONQyPIUFOUbCQ==" - }, "posix-character-classes": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/posix-character-classes/-/posix-character-classes-0.1.1.tgz", diff --git a/package.json b/package.json index 2f5d335a8..adde39656 100644 --- a/package.json +++ b/package.json @@ -28,9 +28,8 @@ }, "dependencies": { "@fortawesome/fontawesome-free": "6.1.2", - "bootstrap": "^4.4.1", - "jquery": "3.5.1", - "optimize-css-assets-webpack-plugin": "^6.0.1", - "popper.js": "^1.16.1" + "@popperjs/core": "^2.11.6", + "bootstrap": "^5.2.2", + "optimize-css-assets-webpack-plugin": "^6.0.1" } } diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 3389d369b..c4b8bbf8b 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -373,7 +373,7 @@ def generate_header_nav_html(n_links_before_dropdown=5): links_dropdown_html = "\n".join(links_dropdown) out += f"""
-
@@ -541,9 +541,9 @@ def navbar_align_class(): """Return the class that aligns the navbar based on config.""" align = context.get("theme_navbar_align", "content") align_options = { - "content": ("col-lg-9", "mr-auto"), - "left": ("", "mr-auto"), - "right": ("", "ml-auto"), + "content": ("col-lg-9", "me-auto"), + "left": ("", "me-auto"), + "right": ("", "ms-auto"), } if align not in align_options: raise ValueError( diff --git a/src/pydata_sphinx_theme/assets/scripts/bootstrap.js b/src/pydata_sphinx_theme/assets/scripts/bootstrap.js index 6c56ac4a0..0238f64d9 100644 --- a/src/pydata_sphinx_theme/assets/scripts/bootstrap.js +++ b/src/pydata_sphinx_theme/assets/scripts/bootstrap.js @@ -1,18 +1,28 @@ -/* Import and setup functions to control Bootstrap's behavior. - * Sphinx injects the html output with jquery and other javascript files. To enable - * Popper.js (and other jQuery plugins) to hook into the same instance of jQuery, - * jQuery is defined as a Webpack external, thus this import uses the externally defined jquery dependency. - */ -import "jquery"; -import "popper.js"; -import "bootstrap"; +// Import and setup functions to control Bootstrap's behavior. +import "@popperjs/core"; +import { Tooltip } from "bootstrap"; +import { documentReady } from "./mixin"; import "../styles/bootstrap.scss"; +/******************************************************************************* + * Trigger tooltips + */ + +/** + * Add tooltip to each element with the "tooltip" data-bs-toogle class + */ +function TriggerTooltip() { + var tooltipTriggerList = [].slice.call( + document.querySelectorAll('[data-bs-toggle="tooltip"]') + ); + tooltipTriggerList.map(function (tooltipTriggerEl) { + return new Tooltip(tooltipTriggerEl, { delay: { show: 500, hide: 100 } }); + }); +} + /******************************************************************************* * Call functions after document loading. - * This is equivalent to the .ready() function as described in - * https://api.jquery.com/ready/ */ -$('[data-toggle="tooltip"]').tooltip({ delay: { show: 500, hide: 100 } }); +documentReady(TriggerTooltip); diff --git a/src/pydata_sphinx_theme/assets/scripts/mixin.js b/src/pydata_sphinx_theme/assets/scripts/mixin.js new file mode 100644 index 000000000..ee860a9aa --- /dev/null +++ b/src/pydata_sphinx_theme/assets/scripts/mixin.js @@ -0,0 +1,13 @@ +/* define several functions to replace jQuery methods + * inspired by https://tobiasahlin.com/blog/move-from-jquery-to-vanilla-javascript/ + */ + +/** + * Execute a method if DOM has finished loading + * + * @param {function} callback the method to execute + */ +export function documentReady(callback) { + if (document.readyState != "loading") callback(); + else document.addEventListener("DOMContentLoaded", callback()); +} diff --git a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js b/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js index 67b13083a..71a7260ea 100644 --- a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js +++ b/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js @@ -1,8 +1,5 @@ -/* Sphinx injects the html output with jquery and other javascript files. - * for jQuery plugin, jQuery is defined as a Webpack external, thus this import - * uses the externally defined jquery dependency. - */ -import "jquery"; +// Define the custom behavior of the page +import { documentReady } from "./mixin"; import "../styles/pydata-sphinx-theme.scss"; @@ -14,6 +11,7 @@ var prefersDark = window.matchMedia("(prefers-color-scheme: dark)"); /** * set the the body theme to the one specified by the user browser + * * @param {event} e */ function autoTheme(e) { @@ -25,6 +23,7 @@ function autoTheme(e) { /** * Set the theme using the specified mode. * It can be one of ["auto", "dark", "light"] + * * @param {str} mode */ function setTheme(mode) { @@ -90,15 +89,17 @@ function addModeListener() { * TOC interactivity */ +/** + * TOC sidebar - add "active" class to parent list + * + * Bootstrap's scrollspy adds the active class to the link, + * but for the automatic collapsing we need this on the parent list item. + * + * The event is triggered on "window" (and not the nav item as documented), + * see https://github.com/twbs/bootstrap/issues/20086 + */ function addTOCInteractivity() { - // TOC sidebar - add "active" class to parent list - // - // Bootstrap's scrollspy adds the active class to the link, - // but for the automatic collapsing we need this on the parent list item. - // - // The event is triggered on "window" (and not the nav item as documented), - // see https://github.com/twbs/bootstrap/issues/20086 - $(window).on("activate.bs.scrollspy", function () { + window.addEventListener("activate.bs.scrollspy", function () { const navLinks = document.querySelectorAll("#bd-toc-nav a"); navLinks.forEach((navLink) => { @@ -116,7 +117,9 @@ function addTOCInteractivity() { * Scroll */ -// Navigation sidebar scrolling to active page +/** + * Navigation sidebar scrolling to active page + */ function scrollToActive() { // If the docs nav doesn't exist, do nothing (e.g., on search page) if (!document.getElementById("bd-docs-nav")) { @@ -164,7 +167,10 @@ function scrollToActive() { /******************************************************************************* * Search */ -/** Find any search forms on the page and return their input element */ + +/** + * Find any search forms on the page and return their input element + */ var findSearchInput = () => { let forms = document.querySelectorAll("form.bd-search"); if (!forms.length) { @@ -211,7 +217,9 @@ var toggleSearchField = () => { } }; -/** Add an event listener for toggleSearchField() for Ctrl/Cmd + K */ +/** + * Add an event listener for toggleSearchField() for Ctrl/Cmd + K + */ var addEventListenerForSearchKeyboard = () => { window.addEventListener( "keydown", @@ -231,7 +239,9 @@ var addEventListenerForSearchKeyboard = () => { ); }; -/** Change the search hint to `meta key` if we are a Mac */ +/** + * Change the search hint to `meta key` if we are a Mac + */ var changeSearchShortcutKey = () => { let forms = document.querySelectorAll("form.bd-search"); var isMac = window.navigator.platform.toUpperCase().indexOf("MAC") >= 0; @@ -242,7 +252,9 @@ var changeSearchShortcutKey = () => { } }; -/** Activate callbacks for search button popup */ +/** + * Activate callbacks for search button popup + */ var setupSearchButtons = () => { changeSearchShortcutKey(); addEventListenerForSearchKeyboard(); @@ -267,22 +279,26 @@ var setupSearchButtons = () => { * - DOCUMENTATION_OPTIONS.pagename * - DOCUMENTATION_OPTIONS.theme_switcher_url */ -// Check if corresponding page path exists in other version of docs -// and, if so, go there instead of the homepage of the other docs version + +/** + * Check if corresponding page path exists in other version of docs + * and, if so, go there instead of the homepage of the other docs version + * + * @param {event} event the event that trigger the check + */ function checkPageExistsAndRedirect(event) { const currentFilePath = `${DOCUMENTATION_OPTIONS.pagename}.html`, tryUrl = event.target.getAttribute("href"); let otherDocsHomepage = tryUrl.replace(currentFilePath, ""); - $.ajax({ - type: "HEAD", - url: tryUrl, - // if the page exists, go there - success: function () { + + fetch(tryUrl, { method: "HEAD" }) + .then(() => { location.href = tryUrl; - }, - }).fail(function () { - location.href = otherDocsHomepage; - }); + }) // if the page exists, go there + .catch((error) => { + location.href = otherDocsHomepage; + }); + // this prevents the browser from following the href of the clicked node // (which is fine because this function takes care of redirecting) return false; @@ -291,9 +307,11 @@ function checkPageExistsAndRedirect(event) { // Populate the version switcher from the JSON config file var themeSwitchBtns = document.querySelectorAll("version-switcher__button"); if (themeSwitchBtns) { - $.getJSON( - DOCUMENTATION_OPTIONS.theme_switcher_json_url, - function (data, textStatus, jqXHR) { + fetch(DOCUMENTATION_OPTIONS.theme_switcher_json_url) + .then((res) => { + return res.json(); + }) + .then((data) => { const currentFilePath = `${DOCUMENTATION_OPTIONS.pagename}.html`; themeSwitchBtns.forEach((btn) => { // Set empty strings by default so that these attributes exist and can be used in CSS selectors @@ -301,7 +319,7 @@ if (themeSwitchBtns) { btn.dataset["activeVersion"] = ""; }); // create links to the corresponding page in the other docs versions - $.each(data, function (index, entry) { + data.forEach((entry) => { // if no custom name specified (e.g., "latest"), use version string if (!("name" in entry)) { entry.name = entry.version; @@ -327,7 +345,7 @@ if (themeSwitchBtns) { node.dataset["versionName"] = entry.name; node.dataset["version"] = entry.version; - $(".version-switcher__menu").append(node); + document.querySelector(".version-switcher__menu").append(node); // replace dropdown button text with the preferred display name of // this version, rather than using sphinx's {{ version }} variable. // also highlight the dropdown entry for the currently-viewed @@ -343,14 +361,17 @@ if (themeSwitchBtns) { }); } }); - } - ); + }); } /******************************************************************************* * MutationObserver to move the ReadTheDocs button */ +/** + * intercept the RTD flyout and place it in the rtd-footer-container if existing + * if not it stays where on top of the page + */ function initRTDObserver() { const mutatedCallback = (mutationList, observer) => { mutationList.forEach((mutation) => { @@ -376,12 +397,10 @@ function initRTDObserver() { /******************************************************************************* * Call functions after document loading. - * This is equivalent to the .ready() function as described in - * https://api.jquery.com/ready/ */ -$(addModeListener); -$(scrollToActive); -$(addTOCInteractivity); -$(setupSearchButtons); -$(initRTDObserver); +documentReady(addModeListener); +documentReady(scrollToActive); +documentReady(addTOCInteractivity); +documentReady(setupSearchButtons); +documentReady(initRTDObserver); diff --git a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss b/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss index dcf0a4f79..1230167e7 100644 --- a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss +++ b/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss @@ -1,4 +1,4 @@ -button.version-switcher__button { +button.btn.version-switcher__button { border-color: var(--pst-color-border); color: var(--pst-color-text-base); // Add a margin on narrow screens to avoid feeling cramped @@ -7,18 +7,24 @@ button.version-switcher__button { margin-bottom: unset; } - &:hover { + &:active { color: var(--pst-color-text-base); + border-color: var(--pst-color-border); } } .version-switcher__menu { border-color: var(--pst-color-border); + border-radius: var(--bs-dropdown-border-radius); a.list-group-item { background-color: var(--pst-color-on-background); color: var(--pst-color-text-base); - border-color: var(--pst-color-border); + padding: 0.75rem 1.25rem; + + &:not(:last-child) { + border-bottom: 1px solid var(--pst-color-border); + } &:hover { background-color: var(--pst-color-surface); diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html index 98ecbc08f..7a37655e7 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html @@ -1,7 +1,7 @@ {%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%} {%- if url | length > 2 %}
  • - {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link", "rel": "noopener", "target": "_blank", "data-toggle": "tooltip"} %} + {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link", "rel": "noopener", "target": "_blank", "data-bs-toggle": "tooltip", "data-bs-placement": "bottom"} %} {%- if attributes %}{% for key, val in attributes.items() %} {% set _ = attributesDefault.update(attributes) %} {% endfor %}{% endif -%} diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html index a99be04b6..13262852b 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html @@ -1,4 +1,4 @@ {# A button that, when clicked, will trigger a search popup overlay #} - diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html index 99acf58db..65c483166 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html @@ -1,4 +1,4 @@ - 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 1209390fa..c15a8b347 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -48,7 +48,7 @@ {% block body_tag %} {# set up with scrollspy to update the toc as we scroll #} {# ref: https://getbootstrap.com/docs/4.0/components/scrollspy/ #} - + {# A button hidden by default to help assistive devices quickly jump to main content #} {# ref: https://www.youtube.com/watch?v=VUR0I5mqq7I #} diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html index bf06dc93d..ded7a00a2 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html @@ -3,11 +3,15 @@ {# If we are remote, add a script to make an HTTP request for the value on page load #} {%- if is_remote %} {#- if announcement text is not remote, populate announcement w/ local content -#} {%- else %} diff --git a/tests/test_build.py b/tests/test_build.py index 849c0d8f9..cd569eee8 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -293,7 +293,7 @@ def test_navbar_align_right(sphinx_build_factory): # Both the column alignment and the margin should be changed index_html = sphinx_build.html_tree("index.html") assert "col-lg-9" not in index_html.select(".navbar-header-items")[0].attrs["class"] - assert "ml-auto" in index_html.select("div#navbar-center")[0].attrs["class"] + assert "ms-auto" in index_html.select("div#navbar-center")[0].attrs["class"] def test_navbar_no_in_page_headers(sphinx_build_factory, file_regression): diff --git a/tests/test_build/navbar_icon_links.html b/tests/test_build/navbar_icon_links.html index 9793e2e3a..a32adaadb 100644 --- a/tests/test_build/navbar_icon_links.html +++ b/tests/test_build/navbar_icon_links.html @@ -1,6 +1,6 @@