[Yt-dev] yt documentation, standards, implementation

j s oishi jsoishi at gmail.com
Thu Jun 3 17:34:21 PDT 2010


Hi,

I just want to briefly make a few extra comments, though I won't add
much to the already excellent discussion. First, I vote for the Numpy
standard as well. However, I think Dave raises a very important point:
dealing with the multidimensional nature of OOP documentation will be
the biggest challenge. I have recently gone through and documented a
very large, extremely object oriented code base (entirely for my own
benefit, as I was the only novice user at the time). I found one of
the biggest challenges in OOP is the notion of multiple entry points
to various objects and their connection to one another (inheritance,
especially). I don't really have a solution to the problems Dave
mentions, but perhaps if we are clear about return values and can
provide some way of linking input parameters to their objects, that
might help a lot toward a "if you like this, why don't you try that"
style.

As a side note, not only does the help(pf.h) not reveal much
information about class relationships, in iyt

In [1]: pf.h?

returns nothing even remotely useful. This is definitely something
that needs resolution, as there is a growing number of interactive yt
users coming from idl-land who may think there is no on-line help if ?
fails.

Like Tom and Matt, I had a great experience with an early manual
typeset with one thing per page. This is a great idea, and I think we
can improve it by setting out some kind of entry point for large yt
concepts. For example with matplotlib, I always start with something
like

fig = figure()
ax = fig.add_axis([0.1,0.1,0.8,0.8])

and that axis object is my entry point to nearly the entire plot. If
we had something that was somewhere in between an API doc and the
manual at large that gave a few starting points and then linked to the
API doc for that entry point, perhaps that might help some.

j



More information about the yt-dev mailing list