Hi, all-- I fully agree with using the Numpy standard. I have a few additions to that, and then another point to bring up. The numpy standard says that the "description" should not reference the variables. I don't think this is strictly necessary, especially since we have narrative descriptions for a lot of functions already. I like the Big List Of Functions that's available on the Numpy docs. It makes "Dang, there has to be a function that does X but I don't know what it's called" much much easier. I would find this kind of thing useful in the yt docs, as well. The numpy docs do a pretty good job of "you might also like" for each function. While this is somewhat more difficult to do, as it takes a pretty global understanding of the code base, it's quite useful. For instance, I had been using h.find_max and h.find_min separately, when h.all_data().quantites['Extrema'] does exactly what I want. This brings me to my other point-- classes, and class inheritance hierarchies. I don't have any good solutions, but I feel that this is one aspect of yt that isn't really well addressed by the Numpy standard, and bears discussion. Even their class suggestions are still pretty 1d and procedural, whereas the hierarchy structure in yt is more like a 3d data space: class/derived class/ method. When one wants to perform an action, you need not only the method, but the correct object to act upon, and as in the find_min vs. Extrama, there may be multiple options for both. Python is only ok about auto documenting methods and members and inheritence resolution for classes. help() on an object or an instance of the object gives some useful things, like method resolution, and some of the methods inherited and from which super class. However, this still leaves a bunch to be desired. For instance, (and this might be my own ignorance) doing
help( pf.h )
doesn't show anything about the availability of pf.h.covering_grid or AMRCovering grid. It also makes the Big Ol' List O' Functions more difficult, or perhaps simply requires a "list by method name" and "list by class" option... My own inexperience with other heavily OOP documentations leaves me without another example that I like (matplotlib is class heavy, but the documentation also leaves a lot to be desired) but I know that some of you are pretty sharp, so might have good suggestions. Those are my thoughts right now. d. On Tue, Jun 1, 2010 at 8:44 AM, Matthew Turk <matthewturk@gmail.com> wrote:
Hi Sam,
This is tricky because we have moved to *args, **kwargs for the arguments, and then the docstring does not explain what the args, kwargs are. Explicitly listing the arguments along with their types and a quick description would be invaluable to new users.
Agreed. In fact, that *specific* example is one I intend to get rid of:
http://yt.enzotools.org/ticket/242
But yes, where kwargs are unavoidable, they should be explicitly listed in the docstring.
As for the format of the docstrings, I am fine with the NumPy standard. I would suggest that whatever the standard becomes that there be a boilerplate example that can just be copied into any new function where developers can edit where necessary, and stick this example somewhere like the doc folder.
Yes, definitely. I intend to not only include a fiducial example like the NumPy docs, but also a list of helpful mechanisms for cross-referencing between objects, as well as idioms for describing common patterns.
Finally, since I do seem to read the majority of commits coming in, I'd be happy to be the guy to remind someone when their docstrings aren't up to snuff.
Great, thanks!
-Matt _______________________________________________ Yt-dev mailing list Yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-- Sent from my Stone Tablet and carried by my Pterodactyl.