How to autodoc a custom descriptor like a property in sphinx?

Question

I have a custom descriptor

@runtime_checkable
class ROProperty(Protocol[T_co]):
    """Protocol for a read-only descriptor."""

    def __get__(self, instance: Any, owner: Any = None) -> T_co | None:
        ...

class ConcreteDesc(ROProperty[T_co]):
    ...

I use it for a class attribute:

prop = ConcreteDesc[int]()

I connect a function in Sphinx conf.py:

def descriptor_annotations(app, what, name, obj, options, signature, return_annotation):
    if isinstance(obj, ROProperty) and not isinstance(obj, property):
        return ("", f"{obj.__orig_class__.__args__[0].__name__} | None")

def setup(app):
    app.connect("autodoc-process-signature", descriptor_annotations)

My actual goal is to get a docstring indistinguishable from a real property:

property prop -> type | None

but, this gives me:

owner.prop -> type | None

I tried connecting to autodoc-before-process-signature event as well, but then descriptor_annotations was called only for dunder methods, which I think is weird.

How to autodoc a custom descriptor like a property in sphinx?

0 Answers0