Add labels/properties to doc-heading about griffe

[pawamoy]

Hey! So, I just pushed version 0.17.0 which brings more labels based on decorators 🙂

• @property gives property label
• if there's a property setter, writable label is added
• if there's a property deleter, deletable label is added
• @staticmethod gives staticmethod label
• @classmethod gives classmethod label
• @functools.cache, @functools.cached_property and @functools.lru_cache give cached label (and I realize I forgot to add a property label when the decorator is cached_property, will add later). It works with brief and full path (@functools.... and @...)
• @abc.abstractmethod gives abstract label (mkdocstrings/mkdocstrings#349)

I think we can close this issue, but please do open issues if you have other ideas for properties! Now that there's basic support it should not be difficult to add more.

[pawamoy]

Great, your help offering is appreciated 🙂
Let me handle a few decorators/labels first, and once I'm confident this can be further improved, I'll let you know 🙂

[pedrolabonia]

Also passing by to show my interest. If you have any feel for how this could be implemented, I could also give it a go :)

[pawamoy]

Hello @wxdrizzle!

You're right, I didn't reapply the same logic for properties in Griffe. The "labels?" item in the TODO list just means: "what labels can we have on each type of object?". For example, we could have staticmethod, like before, but maybe it should be called static instead? Since it's a decorator, will every decorator become a label on an object? Or just the ones that are built-in or in the standard library? How to let users extend that?

Griffe already sets labels on attributes (module-attribute, class-attribute and instance-attribute), because it was easy to do, but for methods it's a bit more complicated. Well, not really for the classic staticmethod, classmethod and property: the decorator is a single name that we can easily match. But others, like @property_name.setter or @abc.abstractmethod need a bit more of work.

If you are interested in contributing something, I can give you some guidance, otherwise I'll eventually get to it 😄

[wxdrizzle]

Hi again @pawamoy !

I think staticmethod and classmethod will be good features to distinguish those methods from other regular methods, although one can directly get that from whether the signature contains no self or contains cls. For me, both staticmethod and static are good.

Adding the label property is also important, but instead we can also simply remove (self) from a property's signature to tell users that they can just use it without a (). For @property_name.setter, maybe the best way is to add a label readonly, but since you said that would need more work, so currently it is sufficient for users to just add "readonly" information in the docstring.

Personally I think Other non-built-in decorators may be another issue, as it may require a context for both users and readers to know what the decorator means. So it may be better if we can provide an option to enable or disable the labels. That could be a long-term plan.

In a nutshell, I'm happy if I can contribute something. I can help add the classic staticmethod, classmethod and property recently, as you said it is not very complicated. For setter and abstractmethod, I'm just not sure if my knowledge is good enough to handle that, but you can also consider to provide some quick guidance and I'm willing to read some tutorials as well. 😉

[pawamoy]

Thanks! I hope I'll be able to get to it soon so I can give you some feedback!