Fix Sphinx canonical links

docs/conf.py

@@ -3,6 +3,11 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent / "extensions"))
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -13,7 +18,7 @@ author = "Andrew Godwin"
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions: list = []
+extensions: list = ["canonical_fix"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -26,3 +31,4 @@ html_theme = "furo"
 html_static_path = ["_static"]
 html_logo = "../static/img/logo-128.png"
 html_favicon = "../static/img/icon-32.png"
+html_baseurl = "https://docs.jointakahe.org/"

docs/extensions/canonical_fix.py

@@ -0,0 +1,30 @@
+from sphinx.application import Sphinx
+from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+
+
+def setup(app: Sphinx):
+    app.connect("html-page-context", canonical_url)
+
+
+def canonical_url(app: Sphinx, pagename, templatename, context, doctree):
+    """Sphinx 1.8 builds a canonical URL if ``html_baseurl`` config is
+    set. However, it builds a URL ending with ".html" when using the
+    dirhtml builder, which is incorrect. Detect this and generate the
+    correct URL for each page.
+    Also accepts the custom, deprecated ``canonical_url`` config as the
+    base URL. This will be removed in version 2.1.
+    """
+    base = app.config.html_baseurl
+
+    if (
+        not base
+        or not isinstance(app.builder, DirectoryHTMLBuilder)
+        or not context["pageurl"]
+        or not context["pageurl"].endswith(".html")
+    ):
+        return
+
+    # Fix pageurl for dirhtml builder if this version of Sphinx still
+    # generates .html URLs.
+    target = app.builder.get_target_uri(pagename)
+    context["pageurl"] = base + target