[Yt-dev] yt documentation, standards, implementation

Matthew Turk matthewturk at gmail.com
Fri Jun 4 23:23:09 PDT 2010


Hi Dave,

> 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.

I'd love some help on this.

> 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?

Absolutely.  And cross-referencing within docs is relatively easy, as well.

> 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.

Okay, sounds good.  I'm looking at how to get this new sphinx
extension "viewcode" working, which should enable us to include the
(highlighted) source directly in the doc builds.

> 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've uploaded a first stab at this:

http://yt.enzotools.org/doc/dev_build/

specifically, the API docs here:

http://yt.enzotools.org/doc/dev_build/api/index.html

It has nothing other than the docstrings -- I'm going to add
descriptions to the individual module / conceptual pages as time goes
on, but right now while auto-generating the splits from the original
way modules were documented means it's still a bit in flux and I
didn't want to have anything get lost.  It took a little while to get
the numpy doc extensions working with the latest Sphinx, but they
should now be in there mostly correctly.

I think this highlights just how bad our docstrings are right now ...

I updated the FixedResolutionBuffer docstring, and using the
autosummary directive the numpy docs will split everything up into
subpages and so on.  Here's the page describing the basics of
plotting:

http://yt.enzotools.org/doc/dev_build/api/plot_types.html

and then if you go to the FRB page:

http://yt.enzotools.org/doc/dev_build/api/generated/plot_types/yt.raven.FixedResolutionBuffer.html

you can see where the methods are all documented and whatnot.  Here's
the source code, for reference:

http://yt.enzotools.org/browser/trunk/yt/raven/FixedResolution.py#L29

Unfortunately, there are a bunch of artifacts in the other docstrings.
 I'm going to try to sketch out rough passes at some of the
docstrings, but it's going to be a while before this is really ready
for primetime.  You can see how it has rendered a bunch of other
things, too.  I think maybe flattening the list a bit more could be
helpful, but I'm just happy that the docstring parser and splitter is
working.  As a quick comment, it'll be easier to move around the
larger organization and outline than it will be to split and unsplit
pages and change the way the docstrings get divvied up.

Thoughts on any of this?  I think this is the closest we've come to
having the single-function-per-page manual, which is becoming more and
more appealing to me.  :)

-Matt



More information about the yt-dev mailing list