Add a test for the @cached_property hack

Author: clayote

pyproject.toml

@@ -48,6 +48,16 @@ tests = [
   "pympler",
   "pytest",
   "pytest-xdist[psutil]",
+  "sphinx",
+  "sphinx-notfound-page"
+  "sphinx-basic-ng",
+  "sphinxcontrib-applehelp",
+  "sphinxcontrib-devhelp",
+  "sphinxcontrib-htmlhelp",
+  "sphinxcontrib-jsmath",
+  "sphinxcontrib-serializinghtml",
+  "sphinxcontrib-towncrier",
+  "myst-parser",
 ]
 cov = [{ include-group = "tests" }, "coverage[toml]"]
 pyright = ["pyright", { include-group = "tests" }]

tests/index.rst

@@ -0,0 +1,3 @@
+.. autoclass:: tests.test_slots.SphinxDocTest
+
+    .. autoproperty:: documented

tests/index.txt

@@ -0,0 +1,7 @@
+class tests.test_slots.SphinxDocTest
+
+   Test that slotted cached_property shows up in Sphinx docs
+
+   property documented
+
+      A very well documented function

tests/test_slots.py

@@ -7,10 +7,15 @@
 import functools
 import pickle
 import weakref
-
+from pathlib import Path
+from tempfile import TemporaryDirectory
 from unittest import mock
 
 import pytest
+try:
+    from sphinx.application import Sphinx
+except ImportError:
+    Sphinx = None
 
 import attr
 import attrs
@@ -735,26 +740,33 @@ def f(self):
     assert B(11).f == 121
     assert B(17).f == 289
 
+@attr.s(slots=True)
+class SphinxDocTest:
+    """Test that slotted cached_property shows up in Sphinx docs"""
 
-def test_slots_cached_property_allows_call():
-    """
-    cached_property in slotted class allows call.
-    """
-
-    @attr.s(slots=True)
-    class A:
-        x = attr.ib()
+    @functools.cached_property
+    def documented(self):
+        """A very well documented function"""
+        return True
 
-        @functools.cached_property
-        def f(self):
-            return self.x
 
-    assert A(11).f == 11
+@pytest.mark.skipif(Sphinx is None, reason="Sphinx is not installed")
+def test_sphinx_autodocuments_cached_property():
+    here = Path(__file__).parent
+    with TemporaryDirectory() as td:
+        tmp_path = Path(td)
+        app = Sphinx(here, here.parent.joinpath("docs"), tmp_path, tmp_path, "text")
+        app.build(force_all=True)
+        with (
+            tmp_path.joinpath("index.txt").open() as written,
+            Path(__file__).parent.joinpath("index.txt").open() as good,
+        ):
+            assert written.read() == good.read()
 
 
-def test_slots_cached_property_has_docstring():
+def test_slots_cached_property_allows_call():
     """
-    cached_property in slotted class carries its original docstring
+    cached_property in slotted class allows call.
     """
 
     @attr.s(slots=True)
@@ -763,10 +775,9 @@ class A:
 
         @functools.cached_property
         def f(self):
-            """What an informative docstring!"""
             return self.x
 
-    assert A(11).f.__doc__ == "What an informative docstring!"
+    assert A(11).f == 11
 
 
 def test_slots_cached_property_class_does_not_have__dict__():