From de34bf5c52d1093bcea7dbcae117532e7b61f382 Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Wed, 24 Jul 2024 07:35:58 +0200
Subject: [PATCH] docs/instrumentation/structlog: add warning re:
 AsyncBoundLogger

---
 docs/conf.py            | 10 ++++++++++
 docs/instrumentation.md |  6 ++++++
 2 files changed, 16 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 0f13bc9..ff55e20 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -2,9 +2,19 @@
 #
 # SPDX-License-Identifier: MIT
 
+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/instrumentation.md b/docs/instrumentation.md
index 7ebddb6..bd6412d 100644
--- a/docs/instrumentation.md
+++ b/docs/instrumentation.md
@@ -60,6 +60,12 @@ If *structlog* instrumentation is active, scheduled retries are logged using a *
 
 You can activate it manually by adding {data}`stamina.instrumentation.StructlogOnRetryHook` to the list of hooks passed to {func}`stamina.instrumentation.set_on_retry_hooks`.
 
+:::{warning}
+*structlog* integration does **not** work with the deprecated `structlog.stdlib.AsyncBoundLogger` because it won't await log method calls.
+Use `structlog.stdlib.BoundLogger` and explicit async methods like `ainfo()` instead of `info()`.
+:::
+
+
 (logging)=
 
 ## Standard Library's `logging`