fix(docs): use environment variable instead of config context for `ht…

…ml_baseurl` (#1049)

Fixes readthedocs builds, which broke some time within the last 24 hours
due to an upstream change which resulted in the `html_baseurl`
variable being set to `""`. 

This has the (positive) side-effect of `<link rel="canonical" />` no
longer always pointing to `stable`, and instead using the version that's
being built. The same applies to the opensearch config.

docs/conf.py

@@ -19,7 +19,6 @@
 import subprocess  # noqa: TID251
 import sys
 from typing import Any, Dict, Optional
-from urllib.parse import urljoin
 
 from sphinx.application import Sphinx
 
@@ -259,11 +258,23 @@ def linkcode_resolve(domain: str, info: Dict[str, Any]) -> Optional[str]:
 if not _IS_READTHEDOCS:
     notfound_urls_prefix = "/"
 
+# ignore common link types that we don't particularly care about or are unable to check
 linkcheck_ignore = [
     r"https?://github.com/.+?/.+?/(issues|pull)/\d+",
     r"https?://support.discord.com/",
 ]
 
+if _IS_READTHEDOCS:
+    # set html_baseurl based on readthedocs-provided env variable
+    # https://github.com/readthedocs/readthedocs.org/pull/10224
+    # https://docs.readthedocs.io/en/stable/reference/environment-variables.html#envvar-READTHEDOCS_CANONICAL_URL
+    html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL")
+    if not html_baseurl:
+        raise RuntimeError("Expected `READTHEDOCS_CANONICAL_URL` to be set on readthedocs")
+
+    # enable opensearch (see description somewhere below)
+    html_use_opensearch = html_baseurl.rstrip("/")
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -360,7 +371,7 @@ def linkcode_resolve(domain: str, info: Dict[str, Any]) -> Optional[str]:
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-# html_use_opensearch = ''
+# html_use_opensearch = ''  # NOTE: this is being set above
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None
@@ -476,19 +487,6 @@ def setup(app: Sphinx) -> None:
         app.config.html_context["discord_invite"] = "https://discord.gg/disnake"
         app.config.resource_links["disnake"] = "https://discord.gg/disnake"
 
-    # readthedocs appends additional stuff to conf.py,
-    # we can't access it above since it wouldn't have run yet
-    if _IS_READTHEDOCS:
-        # this is the "canonical" url, which always points to stable in our case
-        if not (base_url := globals().get("html_baseurl")):
-            raise RuntimeError("Expected `html_baseurl` to be set on readthedocs")
-
-        # special case for convenience: if latest, use that for opensearch
-        if os.environ["READTHEDOCS_VERSION"] == "latest":
-            base_url = urljoin(base_url, "../latest")
-
-        app.config["html_use_opensearch"] = base_url.rstrip("/")
-
     # HACK: avoid deprecation warnings caused by sphinx always iterating over all class attributes
     import disnake