-
-
Notifications
You must be signed in to change notification settings - Fork 367
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
Self documentation - current state #357
Comments
I am also looking at a way to produce documentation, possibly in some json-schema format for my JSON serialization of attrs objects. The key for me is honing on a proper way to add a description or help or doc to an attribute as per @manishtomar in #104 and also to an object (and eventually to nested objects like in @Tinche cattrs) . This could use metadata alright for From then I could introspect my objects to generate some docs. Another helper to me would be @toumorokoshi jsonschema-extractor most likely. It does not handle any doc/help/description though. |
I'd be up for adding functionality into jsonschema-extractor to extract docstring data. I like the example of:
|
It might be nice to collect the use cases for this feature before start talking API? |
As one of the use case for me, I maintain this tool https://github.com/nexB/scancode-toolkit. Internally, this is for now a messy mish-mash of plain objects, plain data structures, namedtuples, attr objects and schematics objects. I would like to move it all to attr and have a not too complicated path to generate sphynx doc, custom docs and json-schema. Having a description attached to a field or object is quite important for any documentation to be meaningful to me. |
@manishtomar @nicholas-mitchell any more input so we can make this move forward? |
@pombredanne My original intent was exactly this. Also it makes the code more readable. |
Interface-wise, added a Perhaps the following will inherently be covered by a Sphynx-type solution, but I will mention it just in case it sparks other ideas. Another type of functionality in which I am most interested is interactive use of the documentation; usually via docstrings in either (1) the interactive prompt, (2) a Jupyter notebook or (3) an IDE. I do this extensively whilst coding, preferring that to finding leaving eh coding environment to find a website with the docs. As I integrate class NormalClass:
"""An class that uses attrs to do interesting stuff.
Parameters
----------
x : {int, float}
a vector - some more useful information
"""
def __init__(self, x):
self.x = x
if not isinstance(x, (int, float)):
# raise an error This could become: @attr.s
def AttrsClass:
"""An class that uses attrs to do interesting stuff.
"""
x = attr.ib(default=None, validator=attr.validators.instance_of((int, float)),
doc='a vector - some more useful information') Then I would end up doing something like this is in an ipython prompt: a = AttrsClass(x=23.5)
# Have a look at the docstring for the class
a? This could then be extended, using the suggested approach of a a.x.doc
# Even perhaps using the ipython helper: ?
a.x? Current functionality of the last line would show information about the Maybe these things could be incorporated into the |
So for extracting information by other tools, you can already use For those who really want that right now, I’m pretty sure you can build yourself a decorator that does the same thing and patches the class’ The open questions are:
2 Seems more complicated than it sounds and I’m not 100% confident we can achieve a solution that is good for everyone. 🤔 Most flexible idea from the top of my head would be to allow for a |
@hynek: agreed. Perhaps |
All seem like good ideas, @hynek @wsanchez Your suggested |
Any news on this one? |
Perhaps a Sphinx extension could pull attributes off the |
Note that https://docs.python.org/3/whatsnew/3.8.html#inspect allows |
Example:class A:
__slots__ = {"one": "one doc"}
help(A.one) Python 3.7:
Python 3.8:
|
One use case I would like in attrs (although that might make more sense as a plugin than as part of the core) is to have an independent JSON Schema (or Ion, or protobuf, or whatever) defining the structure, and then be able to construct an attrs class from it automatically -- essentially an attrs-based equivalent of warlock. |
I don't think there is one format of My use case is to write doc string once for individual attributes and then programmatically display them in command-line arguments and also to generate Sphinx documentation. |
🤔 maybe it would basically move the problem outside the attrs.define
class A:
b: Annotated[str, "b for 🍌"]
c: Annotated[str, "c is for 🍪, of course!"] |
@hynek @chadrik
I've tried following this and other threads and reading the current docs, but can't see if/how one best produces any documentation directly from the
attr.ib()
definitions.If it does not exist, would something like
argparse
be a good example?I suppose the type annotation (e.g. using
attr.s(auto_attribs=True)
is a step in the direction I am thinking/hoping for. I don't know the details, but Emacs does a good job of self-documenting, which is especially useful with the type annotation, as that provides at least some information for each argument.Could someone point me in the right direction, please?
The text was updated successfully, but these errors were encountered: