Improve RTD and run Cog on docs build (#632)

.readthedocs.yaml

@@ -2,10 +2,13 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-lts-latest
   tools:
     # Keep version in sync with tox.ini/docs and ci.yml/docs
     python: "3.12"
+  jobs:
+    pre_build:
+      - cog -rP docs/index.md
 
 python:
   install:

docs/conf.py

@@ -3,9 +3,18 @@
 # 2.0, and the MIT License.  See the LICENSE file in the root of this
 # repository for complete details.
 
+import os
+
 from importlib import metadata
 
 
+# Set canonical URL from the Read the Docs Domain
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context = {"READTHEDOCS": True}
+
 # We want an image in the README and include the README in the docs.
 suppress_warnings = ["image.nonlocal_uri"]
 

docs/index.md

@@ -12,6 +12,8 @@ Release **{sub-ref}`release`**  ([What's new?](https://github.com/hynek/structlo
 ```
 
 <!-- [[[cog
+# This is mainly called from RTD's pre_build job!
+
 import pathlib, tomllib, importlib.metadata
 
 if "dev" in (version := importlib.metadata.version("structlog")):

pyproject.toml

@@ -48,6 +48,7 @@ tests = [
 # Otherwise mypy fails in tox.
 typing = ["mypy>=1.4", "rich", "twisted"]
 docs = [
+    "cogapp",
     "furo",
     "myst-parser",
     "sphinx",