-
-
Notifications
You must be signed in to change notification settings - Fork 379
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
Generate attribute documentation #104
Comments
Um do you have any idea on how to achieve that? :) |
It might be easier to generate the |
I think adding a doc keyword to attr.ib would be very helpful. I am looking to have the interactive help command give more details/a better doc string for the init function in addition to the sphinx docs. Is there agreement that this is a useful feature to add? Are there any plans to implement this? |
Will need @hynek 's executive approval :)
I can try to implement over a few weekends. I am super slammed on weekdays and also some weekends :( unless someone else would like contribute before that. |
Why don't you make an addon library. This doesn't have to go into attrs itself at first.
The implementation of |
@manishtomar thanks for the insight. If @hynek can weight in on wheter this fits into attrs or not would be helpful. I do think that a simple way to inject a doc string into the attr.ib call will make the code more self documenting in the realm where I am using attrs. If not, the addon approach that @Tinche suggested might be the way to go. |
My original question was kind of how to achieve the complete autodoc? IOW how do you want to go from: @attr.s
class C:
"""This is class C."""
x = attr.ib(doc="This is attribute x.") to a docstring like:
Do you want attrs to generate the ivar block for you and append it or what’s the plan? I guess my overall question is: what do you want to do with the doc string that warrants to add it rather than go Tin’s suggestion of metadata? |
Yes.
I just want attribute's documentation to live next to its definition and have it generate the ivar block. I am fine with either of suggestion. Although having in attrs seems nicer. |
I guess we could add it optionally? Something like |
Oh yes. My intention was always it being optional.
I was thinking more like |
I think they are very much the same. Let’s use #357 since it’s more discoverable atm. |
It would nice if sphinx based documentation can be automatically generated from validators when possible. For example, following class
could be simplified by
Since the docs are next to attribute definition it makes the docs more comprehensible.
The text was updated successfully, but these errors were encountered: