docs/instrumentation/structlog: add warning re: AsyncBoundLogger

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"]
 

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`