-
-
Notifications
You must be signed in to change notification settings - Fork 374
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Ability to add a doc string to attr.ib #8
Comments
I’ve played with it a bit but I’m not sure it’s possible when not using properties that are pretty special. :-/ Gotta dig deeper… |
Reading the answers of http://stackoverflow.com/questions/5793306/python-get-doc-documentation-for-instance-variable#5793396 it seems to me that the only reason it work with your properties is they’re methods underneath. So unless you find a way to add doc strings to data attributes without wrapping them using properties, I’m afraid this is impossible. |
Have you considered appending documentation for attributes to the class's docstring? Or the One other thing I noticed is that if you set default to an attr.Factory, sphinx shows the default as |
does that work? care to provide a PR/PoC? 😇 |
I've actually just started documenting the attributes as :param: in the class docstring, which sphinx renders pretty nicely: http://effect.readthedocs.org/en/latest/apidocs.html#effect.Effect This seems like probably the best solution, since if attrs were to modify the docstring, it'd have to assume a documentation format, which may be wrong (e.g. older projects still use epytext). |
Yes, that’s why my init has no docstring. I removed it on Lynn’s request for this very reason. :) |
You can add docstrings using descriptors. I suppose that's not different enough from properties though? class Descriptor:
def __init__(self, doc_str):
self.__doc__ = doc_str
def __set_name__(self, owner, attr):
self.attr = attr
def __get__(self, instance, inst_type):
return getattr(instance, f"_{self.attr}")
def __set__(self, instance, value):
setattr(instance, f"_{self.attr}", value)
class Foo:
bar = Descriptor("Example Docstring")
foo = Foo()
help(foo) You'll have to excuse me as I just discovered your library after trying out Edit: I suppose what I did is not exactly what OP is doing. |
This is semi-possible now because of the @attr.s(auto_attribs=True)
class SomeClass:
a_number: int = 42
"""Something descriptive about ``a_number``.""" It's still ignored by Python so |
Somehow param does this. See the "doc" keyword: https://param.holoviz.org/user_guide/Parameters.html#parameter-metadata |
If I read the docs correctly, it just appends a And since it came up the other day on StackOverflow to reinforce: the canonical way of documenting attributes of a class in Python is currently in the |
@hynek - what's the best way to specify the doc/help for a particular attribute when using My specific use case is trying to get this somewhere better: time_limit: int = None # in minutes |
There is none; the community way is to put all your docs into the class docstring by hand. Adding templating magic would list likely break along the various consumers of it. 😐 To be fair, there's no boilerplate of repetition. It's just about the position where you put your docs. |
Current behavior:
Desired behavior:
(or something like that)
Similar to doing:
The text was updated successfully, but these errors were encountered: