From 92f5110474aba1cac0516780a27afeffe7f96ac3 Mon Sep 17 00:00:00 2001 From: gabalafou Date: Tue, 12 Nov 2024 03:20:45 -0500 Subject: [PATCH] Stop moving the Read the Docs version switcher into the sidebar (#2034) Read the Docs recently rolled out its new "addons" project. This broke assumptions made by code in our theme. In particular, it means that all of the code that tries to move the Read the Docs version switcher into the sidebar no longer works, so this pull request removes all of that code and updates the docs. I also removed the check for Read the Docs in the Ethical Ads template because as far as I understand, that template is opt-in anyway, meaning that sites that use our theme do not have that template included by default. Fixes https://github.com/pydata/pydata-sphinx-theme/issues/1794 and possibly https://github.com/pydata/pydata-sphinx-theme/issues/1238. This pull request does not address https://github.com/pydata/pydata-sphinx-theme/issues/1933, which is about providing a better integration with Read the Docs. The only goal of this pull request is to remove code that is broken as a result of the addons rollout. --- docs/user_guide/readthedocs.md | 28 +++++--- .../assets/scripts/pydata-sphinx-theme.js | 32 --------- .../components/_readthedocs-switcher.scss | 70 ------------------- .../assets/styles/pydata-sphinx-theme.scss | 1 - .../components/sidebar-ethical-ads.html | 14 ++-- .../sections/sidebar-primary.html | 2 - tests/test_build/sidebar_subpage.html | 6 +- 7 files changed, 30 insertions(+), 123 deletions(-) delete mode 100644 src/pydata_sphinx_theme/assets/styles/components/_readthedocs-switcher.scss diff --git a/docs/user_guide/readthedocs.md b/docs/user_guide/readthedocs.md index 40818427a..8d818bbe5 100644 --- a/docs/user_guide/readthedocs.md +++ b/docs/user_guide/readthedocs.md @@ -4,14 +4,26 @@ This theme comes with support for {{ rtd }}, a popular service for hosting docum ## Version switcher -Projects hosted on {{ rtd }} can use the {{ rtd }} supplied version switcher instead of the [version switcher that this theme provides](version-dropdown.rst). -Its presence will be automatically detected by this theme, and placed in the `rtd-footer-container` node inside the primary sidebar. - -```{warning} -The {{ rtd }} version switcher will be hidden any time the primary sidebar is hidden (see [this section](layout-sidebar-primary) for discussion of when the primary sidebar might get hidden automatically and how to hide it purposely). -We intend to make {{ rtd }} switcher placement more flexible; you can track progress toward that in [this issue](https://github.com/pydata/pydata-sphinx-theme/issues/705). This problem doesn't apply to the version switcher provided by -the [flyout add-on](https://docs.readthedocs.io/en/stable/addons.html) which can be enabled through your project's settings. -``` +Read the Docs provides a version switcher by default to projects as part of a +[flyout menu](https://docs.readthedocs.io/en/stable/flyout-menu.html) that can +be disabled. + +This means that you have one of three options if you are hosting a PyData +Sphinx Theme-enabled site on Read the Docs: + +1. Use only the Read the Docs version switcher. You must disable the [version + switcher that this theme provides](version-dropdown.rst) if you previously + enabled it. +2. Use only this theme's version switcher. You must disable the Read the Docs + version switcher by going to your project's [Read the Docs + dashboard](https://app.readthedocs.org/dashboard/). Then go to + `Settings > Addons > Flyout menu` and uncheck the "Flyout enabled" box. +3. Not recommended: use both version switchers. + +Be aware that the two version switchers are not feature equivalent. For example, +the Read the Docs flyout provides a translation switcher in addition to a +version switcher. On the other hand, the Read the Docs switcher is not styled to +match the look and feel of this theme. And there are other differences. ## Add ethical advertisements to your sidebar 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 3e5f6c9f7..f244c75a7 100644 --- a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js +++ b/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js @@ -609,37 +609,6 @@ function showVersionWarningBanner(data) { banner.classList.remove("d-none"); } -/******************************************************************************* - * 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) => { - // Check whether the mutation is for RTD, which will have a specific structure - if (mutation.addedNodes.length === 0) { - return; - } - if (mutation.addedNodes[0].data === undefined) { - return; - } - if (mutation.addedNodes[0].data.search("Inserted RTD Footer") != -1) { - mutation.addedNodes.forEach((node) => { - document.getElementById("rtd-footer-container").append(node); - }); - } - }); - }; - - const observer = new MutationObserver(mutatedCallback); - const config = { childList: true }; - observer.observe(document.body, config); -} - 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 @@ -880,7 +849,6 @@ documentReady(addModeListener); documentReady(scrollToActive); documentReady(addTOCInteractivity); documentReady(setupSearchButtons); -documentReady(initRTDObserver); documentReady(setupMobileSidebarKeyboardHandlers); // Determining whether an element has scrollable content depends on stylesheets, diff --git a/src/pydata_sphinx_theme/assets/styles/components/_readthedocs-switcher.scss b/src/pydata_sphinx_theme/assets/styles/components/_readthedocs-switcher.scss deleted file mode 100644 index 3e038bf41..000000000 --- a/src/pydata_sphinx_theme/assets/styles/components/_readthedocs-switcher.scss +++ /dev/null @@ -1,70 +0,0 @@ -.bd-sidebar-primary div#rtd-footer-container { - position: sticky; - bottom: -1rem; - margin: -1rem; // ignore sidebar padding - - .rst-versions.rst-badge { - position: unset; - font-size: 0.9em; - font-family: var(--pst-font-family-base); - max-width: unset; - - .rst-current-version { - display: flex; - align-items: center; - gap: 0.2rem; - height: 2.5rem; - transition: background-color 0.2s ease-out; - background-color: var(--pst-color-background); - color: var(--pst-color-success); - border-top: 1px solid var(--pst-color-border); - } - - .fa.fa-book { - color: var(--pst-color-text-muted); - margin-right: auto; - - &::after { - color: var(--pst-color-text-base); - content: "Read The Docs"; - font-family: var(--pst-font-family-base); - font-weight: var(--pst-admonition-font-weight-heading); - } - } - - .fa.fa-caret-down { - color: var(--pst-color-text-muted); - } - } - - .rst-versions.rst-badge.shift-up { - .rst-current-version { - border-bottom: 1px solid var(--pst-color-border); - } - } - - .rst-other-versions { - background-color: var(--pst-color-surface); - color: var(--pst-color-text-base); - - dl { - dd a { - color: var(--pst-color-text-muted); - } - } - - hr { - background-color: var(--pst-color-border); - } - - small a { - color: var(--pst-color-link); - } - - input { - padding-left: 0.5rem; - border: 1px solid var(--pst-color-border); - background-color: var(--pst-color-surface); - } - } -} diff --git a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss index 5ed816b55..ff20f0e4a 100644 --- a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss +++ b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss @@ -50,7 +50,6 @@ @import "./components/toc-inpage"; @import "./components/versionmodified"; @import "./components/indices"; -@import "./components/readthedocs-switcher"; // Content blocks in standard Sphinx @import "./content/admonitions"; diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html index aa55904ac..e696ef738 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html @@ -1,9 +1,7 @@ {# For sites hosted on ReadTheDocs, displays "ethical ads". #} -{% if READTHEDOCS %} -
-
-{% endif %} +
+
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html index 378643bc4..4b0cf62c1 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html @@ -37,7 +37,5 @@
{%- include sidebartemplate %}
{%- endfor %} - {# add the rtd flyout in the sidebar if existing #} - {% endif %} {% endblock docs_sidebar %} diff --git a/tests/test_build/sidebar_subpage.html b/tests/test_build/sidebar_subpage.html index 54a4a2e49..6c6c57849 100644 --- a/tests/test_build/sidebar_subpage.html +++ b/tests/test_build/sidebar_subpage.html @@ -68,7 +68,9 @@
-
-