Write a Sphinx extension to document @cached_property on slots classes

Author: clayote

docs/conf.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: MIT
 
 import os
+import sys
 
 from importlib import metadata
 from pathlib import Path
@@ -59,6 +60,7 @@
     "sphinx.ext.todo",
     "notfound.extension",
     "sphinxcontrib.towncrier",
+    "attrs.sphinx_cached_property",
 ]
 
 myst_enable_extensions = [

src/attr/_make.py

@@ -903,7 +903,7 @@ def _create_slots_class(self):
             names += ("__weakref__",)
 
         cached_properties = {
-            name: cached_prop.func
+            name: cached_prop
             for name, cached_prop in cd.items()
             if isinstance(cached_prop, cached_property)
         }
@@ -912,8 +912,11 @@ def _create_slots_class(self):
         # To know to update them.
         additional_closure_functions_to_update = []
         if cached_properties:
+            # Store cached property functions for the autodoc extension to read
+            cd["__attrs_cached_properties__"] = cached_properties
             class_annotations = _get_annotations(self._cls)
-            for name, func in cached_properties.items():
+            for name, prop in cached_properties.items():
+                func = prop.func
                 # Add cached properties to names for slotting.
                 names += (name,)
                 # Clear out function from class to avoid clashing.
@@ -928,7 +931,9 @@ def _create_slots_class(self):
                 additional_closure_functions_to_update.append(original_getattr)
 
             cd["__getattr__"] = _make_cached_property_getattr(
-                cached_properties, original_getattr, self._cls
+                {name: prop.func for (name, prop) in cached_properties.items()},
+                original_getattr,
+                self._cls
             )
 
         # We only add the names of attributes that aren't inherited.

src/attrs/sphinx_cached_property.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+
+from sphinx.application import Sphinx
+
+
+def get_cached_property_for_member_descriptor(cls: type, name: str, default=None):
+	props = getattr(cls, "__attrs_cached_properties__", None)
+	if props is None or name not in props:
+		return getattr(cls, name, default)
+	return props[name]
+
+def setup(app: Sphinx):
+	app.add_autodoc_attrgetter(object, get_cached_property_for_member_descriptor)