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
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@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:
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@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
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
participants (2)
-
Britton Smith -
Matthew Turk