[Yt-dev] New documentation

[Britton Smith]

Matt and company,

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.

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.

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.

Britton

On Wed, Sep 30, 2009 at 1:28 PM, Matthew Turk <matthewturk at gmail.com> wrote:

> Hi guys,
>
> I've been working in the evenings (and, today, during the day a little
> bit...) on the documentation.  Britton, Stephen and Jeff have also
> chipped in and written a bunch.
>
> I've uploaded a new build of the docs (which will last until the next
> svn commit, at which point it'll be wiped and replaced with whatever
> is in SVN currently) to here:
>
> http://yt.enzotools.org/doc/
>
> There are two new features I wanted to mention:
>
>  * The cookbook ( http://yt.enzotools.org/doc/cookbook/recipes.html )
> is programmatically generated from the cookbook repository (
> http://hg.enzotools.org/cookbook ) and images are generated
> automatically as well.  All other locations of examples will be wiped
> and either left empty or replaced with links or content
> programmatically generated from the cookbook repository.  It is 100%
> my fault, but we have too many scattered, sometimes broken, sometimes
> outdated, undocumented examples all over the place.  This is my
> attempt to fix that.
>
>  * I've added comments to every page in the documentation using
> disqus.com.  Currently you need an OpenID (gmail supplies this) to
> comment.  All comments are aggregated on a single page on disqus's
> site, or they can be viewed threaded-inline in the docs.  This can be
> expanded to accept Facebook logins, but I was hesitant on that.  What
> are y'all's thoughts?
>
> Also, there are still some major blank spaces in the docs.  I'm
> working on filling them in, as are other people (mentioned above).  If
> you'd like to help out, pick out a spot, clone the yt-doc repo, add
> text or images or whatever, and I'll give you push privs.  (Of course,
> as soon as you clone a repo, you already have commit privs.  :)
>
> -Matt
> _______________________________________________
> Yt-dev mailing list
> Yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20090930/e26c62d5/attachment.html>