[Yt-dev] yt documentation, standards, implementation

[Matthew Turk]

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