Merge pull request ethereum#15485 from ethereum/rtd-docs-workaround

Fix broken flyout layout due to RTD addons upgrade

docs/_static/js/initialize.js

@@ -23,18 +23,24 @@ function rearrangeDom() {
   document.body.prepend(wrapperDiv);
 
   const rstVersions = document.querySelector(".rst-versions");
-  rstVersions.remove();
   const wyNavSide = document.querySelector("nav.wy-nav-side");
-  wyNavSide.appendChild(rstVersions);
+  // NOTE: Since RTD migration to addons, `.rst-versions` is no longer present in the DOM.
+  // The following code is kept for compatibility with older versions.
+  // See: https://github.com/readthedocs/readthedocs.org/issues/11474
+  if (rstVersions && wyNavSide) {
+    rstVersions.remove();
+    wyNavSide.appendChild(rstVersions);
+  }
   const backdrop = document.createElement("div");
   backdrop.classList.add("backdrop");
   wrapperDiv.appendChild(backdrop);
 
   const content = document.querySelector(".wy-nav-content");
-  content.id = "content";
-  const oldWrap = document.querySelector("section.wy-nav-content-wrap");
-  oldWrap.remove();
-  document.querySelector(".wy-grid-for-nav").appendChild(content);
+  if (content) {
+    content.id = "content";
+    document.querySelector("section.wy-nav-content-wrap")?.remove();
+    document.querySelector(".wy-grid-for-nav")?.appendChild(content);
+  }
 }
 
 function buildHeader() {
@@ -144,8 +150,15 @@ const updateActiveNavLink = () => {
 document.addEventListener("locationchange", updateActiveNavLink);
 
 function updateGitHubEditPath() {
-  // Replaces the version number in the GitHub edit path with "develop"
+  // Replaces the version number in the GitHub edit path with "develop" if it exists.
+  // This is to ensure that the edit path always points to the `develop` branch instead of the specific version branch.
+  // Note that it will fail silently if the anchor element is not found, i.e. the page is not editable or
+  // if the sphinx_rtd_theme is updated to a version that changes the anchor element.
+  // See: https://github.com/readthedocs/sphinx_rtd_theme/blob/a1c2147b17cbf0e57b7d7a6450ad4d9a5ff362cf/sphinx_rtd_theme/breadcrumbs.html#L35
+  // TODO: We should consider a more robust way to handle this in the future.
   const gitHubEditAnchor = document.querySelector(".wy-breadcrumbs-aside > a");
+  if (!gitHubEditAnchor) return;
+
   const url = new URL(gitHubEditAnchor.href);
   const split = url.pathname.split("/");
   const versionIndex = split.indexOf("blob") + 1;
@@ -195,10 +208,12 @@ function initialize() {
     .querySelector(":root")
     .setAttribute("style", `--color-scheme: ${mode}`);
 
+  // NOTE: Since RTD migration to addons, the elements below are no longer present in the DOM.
+  // The following code is kept for compatibility with older versions.
   // Remove old input and RTD logo anchor element
-  document.querySelector("input[name=mode]").remove();
-  document.querySelector("label[for=switch]").remove();
-  document.querySelector(".wy-side-nav-search > a").remove();
+  document.querySelector("input[name=mode]")?.remove();
+  document.querySelector("label[for=switch]")?.remove();
+  document.querySelector(".wy-side-nav-search > a")?.remove();
 
   // Add footer note
   addFooterNote();
@@ -239,7 +254,7 @@ document.addEventListener("click", handleClick);
 
 const handleKeyDown = (e) => {
   if (e.metaKey && e.key === "k") {
-    document.querySelector("#rtd-search-form input").focus();
+    document.querySelector("#rtd-search-form input")?.focus();
   } else if (e.key === "Escape") {
     toggleMenu({ force: false });
   }

docs/conf.py

@@ -36,8 +36,55 @@ def setup(sphinx):
     sphinx.add_css_file('css/custom-dark.css')
     sphinx.add_css_file('css/pygments.css')
 
-# -- General configuration ------------------------------------------------
+# -- RTD GitHub configuration ---------------------------------------------
+
+# Taken from:
+# https://github.com/readthedocs/readthedocs.org/blob/e366e7fc8649fbcf1b6d06ecc12c5f7766144c46/readthedocs/projects/constants.py#L350
+GITHUB_REGEXS = [
+    re.compile(r"github.com/(.+)/(.+)(?:\.git){1}$"),
+    # This must come before the one without a / to make sure we don't capture the /
+    re.compile(r"github.com/(.+)/(.+)/"),
+    re.compile(r"github.com/(.+)/(.+)"),
+    re.compile(r"github.com:(.+)/(.+)\.git$"),
+]
+
+# Taken and adapted from:
+# https://github.com/readthedocs/readthedocs.org/blob/e366e7fc8649fbcf1b6d06ecc12c5f7766144c46/readthedocs/builds/utils.py#L24
+def get_github_username_repo(url):
+    if "github" in url:
+        for regex in GITHUB_REGEXS:
+            match = regex.search(url)
+            if match:
+                return match.groups()
+    return (None, None)
+
+display_github = False
+# NOTE: RTD_DISPLAY_GITHUB, RTD_GITHUB_USER and RTD_GITHUB_REPO are set in the RTD project settings
+github_user = os.getenv("RTD_GITHUB_USER")
+github_repo = os.getenv("RTD_GITHUB_REPO")
+
+if github_user and github_repo:
+    display_github = True
+else:
+    git_clone_url = os.getenv("READTHEDOCS_GIT_CLONE_URL")
+    if git_clone_url:
+        github_user, github_repo = get_github_username_repo(git_clone_url)
+        if github_user and github_repo:
+            display_github = True
+
+display_github_env = os.getenv("RTD_DISPLAY_GITHUB")
+if display_github_env:
+    display_github = display_github_env.lower() == "true"
+
+html_context = {
+    "display_github": display_github,
+    "github_user": github_user,
+    "github_repo": github_repo,
+    "github_version": os.getenv("READTHEDOCS_VERSION", "develop"),
+    "conf_py_path": "/docs/",
+}
 
+# -- General configuration ------------------------------------------------
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'