[Yt-dev] New documentation

[Matthew Turk]

Hi Britton,

> I really like the way the docs are shaping up.  The layout looks nice and
> the disqus comment section is a really nice addition.  Is there a way to
> have an author be notified in some manner when a comment is left on a doc
> page that they wrote?  As the author of a page, I feel like I'm probably
> unlikely to return to that article very frequently as I'm already quite
> familiar with the subject matter.

Definitely!  You can already get RSS, and if you leave a comment you
can get emails whenever a new one is added.  Let me see if there's a
way to subscribe yourself for emails without leaving a comment
yourself.  I'm sure it's possible.

> I also second the idea of centralizing all things related to code examples.
> The cookbook is a nice place, since new users are given a menu of things
> they can do right on the cookbook page.  I feel code examples are more
> likely to get checked out and used if there's an easy place to be made aware
> of their existence.

I think you're right, too.  I'm toying with the idea of making a very
simple "wget"-like addon to the yt command:

$ yt cookbook simple_slice

that would download simple_slice, much like the yt_lodgeit.py app
grabs from the pastebin.  Because the scripts are all stored in hg,
this is not too hard at all.  The only thing I'm not sure of is how to
get the list of available scripts...  but I suspect that can be
handled, too.

> Finally, I think the cookbook could use one more section for extensions
> recipes, that is using the stuff in yt/extensions.  I'm thinking of the halo
> finders, halo profiler, light cone, EnzoSimulation class, etc.  The docs
> already have a section for extensions, but I think there's a distinction
> between the extensions docs and extensions recipes.  For example, I will
> write a doc page for the EnzoSimulation class, but also have a page on how
> to use this with the halo profiler that I think belongs in the cookbook.

I agree.  Right now it's just very simple things.  But I believe we
need a more full cookbook, with the stuff that both you and Stephen
have written.  Maybe we need a section that could be thought of as
"ingredients" and one that could be thought of as "recipes."  I think
maybe better names than those can be conjured up, however.  ;)  But, I
do agree, and I'll work on making that happen.

Thanks for your feedback!

-Matt