Add conf.py comment and require Sphinx>=8.2.3

- Add explanatory comment for override_image_directive=False setting
  explaining it's required for RST badge :target: option support
- Update sphinx>=8.2.3 in docs optional dependency (highest version
  compatible with furo's sphinx<9.0 constraint)

Note: This work was completed with AI assistance (Claude Code).

Author: oberstet

docs/conf.py

@@ -174,6 +174,9 @@ def use_aio():
 ]
 
 # -- sphinxcontrib-images Configuration --------------------------------------
+# NOTE: override_image_directive must be False to preserve standard RST image
+# directive :target: option support, which is required for clickable badge
+# substitutions in docs/index.rst (e.g., |PyPI| |Python| |CI| etc.)
 images_config = {
     "override_image_directive": False,
     "default_image_width": "80%",

pyproject.toml

@@ -102,7 +102,7 @@ dev-latest = [
 # Documentation tools (used by RTD via .readthedocs.yaml)
 docs = [
     # Core Sphinx + MyST
-    "sphinx>=7.2",
+    "sphinx>=8.2.3",
     "myst-parser>=2.0",
 
     # Theme