[Yt-dev] yt documentation, standards, implementation

[david collins]

Hi--

tl:dr  Let's make these lists:

>  * We need a Big List Of Functions, which might also include "Big List
> Of Data Sources", "Big List Of Quantities", "Big List Of Fields" and
> "Big List Of Callbacks."

I think that all of these Big Lists would be great.  I would use them
every day.  I can help with docs on these, if you need.

>  * The current mechanism for generating data sources
> ("pf.h.something(...)"), which made sense when it was first
> implemented, doesn't necessarily help us in the problem of getting
> info from docstrings.

I think that the above Bigs Lists would go a long way to helping this.
 Perhaps we could stick a reference to the web page in the doc string
of things we know are going to be problematic?

> objects.  I'm just about ready at this point to scrap most of the
> documentation that I've written and start anew, but unfortunately
> that's a daunting task.  Documenting is not only hard to sit down and

I think all the existing docs are good, there definitely isn't
anything that I would scrap.  I think we just need to keep filling the
parameter space of ways to use yt.  Right now, I'm personally most
interested in the Big Lists of Things, because I've read all the cook
book pages, and the only documentation left is the source code.  The
source is pretty readable, but it takes much longer to get what I need
that way.

I think "Big Lists Of Stuff" should be the next push.  I think if we
start with the ones Matt mentioned, that would get us a long way.
Quantities, fields, and callbacks are all pretty straight forward and
can just follow the Numpy format.  I think that the Big List of Data
Sources will need more info.  I'll think about a structure that would
be useful for that.

I would add those lists straight to your Table of Contents.  I would
like it if it were pretty high level.  If you make the list, I can
help with filling out the details.


d.