diff --git a/docs/_static/js/initialize.js b/docs/_static/js/initialize.js index a20d4fce7190..1c3be8aaddaa 100644 --- a/docs/_static/js/initialize.js +++ b/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 }); } diff --git a/docs/conf.py b/docs/conf.py index 9c9e2d5a0643..f57a3b5b904c 100644 --- a/docs/conf.py +++ b/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'