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 #1794 and
possibly #1238.

This pull request does not address
#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.

Author: gabalafou

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
 

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,

src/pydata_sphinx_theme/assets/styles/components/_readthedocs-switcher.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";

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

@@ -1,9 +1,7 @@
 {# For sites hosted on ReadTheDocs, displays "ethical ads". #}
-{% if READTHEDOCS %}
-  <div id="ethical-ad-placement"
-       class="flat"
-       data-ea-publisher="readthedocs"
-       data-ea-type="readthedocs-sidebar"
-       data-ea-manual="true">
-  </div>
-{% endif %}
+<div id="ethical-ad-placement"
+      class="flat"
+      data-ea-publisher="readthedocs"
+      data-ea-type="readthedocs-sidebar"
+      data-ea-manual="true">
+</div>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html

@@ -37,7 +37,5 @@
       <div class="sidebar-primary-item">{%- include sidebartemplate %}</div>
     {%- endfor %}
   </div>
-  {# add the rtd flyout in the sidebar if existing #}
-  <div id="rtd-footer-container"></div>
 {% endif %}
 {% endblock docs_sidebar %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html

@@ -68,7 +68,9 @@
   </div>
  </div>
  <div class="sidebar-primary-items__end sidebar-primary__section">
- </div>
- <div id="rtd-footer-container">
+  <div class="sidebar-primary-item">
+   <div class="flat" data-ea-manual="true" data-ea-publisher="readthedocs" data-ea-type="readthedocs-sidebar" id="ethical-ad-placement">
+   </div>
+  </div>
  </div>
 </div>