What is the best long-term support path for documenting class properties while using autodoc?

[sirosen]

In Python 3.9, we were allowed to stack classmethod with property, before the problems with this pattern were fully realized. Sphinx added support for this to autodoc, but support for these descriptors being composed was pulled in Python 3.10.

As Python 3.9 EOL approaches, it seems appropriate to think of the future of Sphinx support for class properties. There are several third-party implementations, making various tradeoffs, and it's easy to write your own read-only one, e.g.:

# various implementations possible; this is just a sample
class classproperty[T, R]:
    def __init__(self, func: t.Callable[[type[T] | T], R]) -> None:
        self.func = func

    def __get__(self, obj: T | None, cls: type[T]) -> R:
        if obj is None:
            return self.func(cls)
        return self.func(obj)

Because autodoc treats stacked decorators as indicating classproperty-ness, you can make a sphinx-friendly version by detecting whether or not a doc build is running and dispatching between implementations. e.g.,

if _in_sphinx_build():
    def classproperty(func):
        return classmethod(property(func))
else:
    ... # real classproperty here

This works great! But it doesn't seem certain that it will last. classmethod(property(...)) only works in CPython 3.9, no other versions, and probably not at all in other implementations.

Looking at the Python Domain definition, py:property has a :classmethod: option. That seems less likely to be removed -- since various third-party implementations of class properties exist, this is a good way to document them.

So! I'm very curious. What's the best way, long-term, for users of class properties to document them? Right now, I'm considering switching off of the build-detection approach (I'm doing it by checking sys.argv[0], but other methods are possible) and onto an explicit py:property definition.