From d4ea660b90408ad8b76541231d23f4543aa4044a Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Wed, 17 Jul 2024 13:35:16 +0200
Subject: [PATCH] Improve RTD and run Cog on docs build (#632)

---
 .readthedocs.yaml | 5 ++++-
 docs/conf.py      | 9 +++++++++
 docs/index.md     | 2 ++
 pyproject.toml    | 1 +
 4 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 7b669cdc..0258b66b 100644
--- a/.readthedocs.yaml
+++ b/.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:
diff --git a/docs/conf.py b/docs/conf.py
index d95868f8..fc28d61a 100644
--- a/docs/conf.py
+++ b/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"]
 
diff --git a/docs/index.md b/docs/index.md
index b9b700c1..e48b5848 100644
--- a/docs/index.md
+++ b/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")):
diff --git a/pyproject.toml b/pyproject.toml
index ec8b885f..865cd877 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -48,6 +48,7 @@ tests = [
 # Otherwise mypy fails in tox.
 typing = ["mypy>=1.4", "rich", "twisted"]
 docs = [
+    "cogapp",
     "furo",
     "myst-parser",
     "sphinx",