[Yt-dev] yt documentation, standards, implementation

[david collins]

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 at 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 at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>



-- 
Sent from my Stone Tablet and carried by my Pterodactyl.