Hi all,

I think if we don't take this opportunity to use notebooks during this major update to the documentation, we'll be kicking ourselves in about a year for missing it.  I'd like to voice my support for the following layout:

1) Write the cookbook examples in a notebook, annotating it with comments and reasoning in markdown cells. Use some amount of conventions for data loading so that with minimal work users could change the path to the data and run themselves.
2) Display the notebooks in the docs
3) Allow for download of both a stripped down (no images included) .ipynb and nbconverted script.

The neat thing is that now you have all these .ipynb files in the doc repo. It would be stupid simple to then show people how to go to that folder, launch yt notebook, you can then interactively execute the examples after pointing to the data locations.  This would be really really nice in my opinion.

Cheers,
Sam



On Wed, Oct 23, 2013 at 10:02 PM, Elizabeth Tasker <tasker@astro1.sci.hokudai.ac.jp> wrote:
Hi everyone,

I agree with Brian. I've only recently discovered python notebooks and I love them for my own analysis and when I'm looking at data together with my students and we're exploring data sets, but I feel they are unnecessary cumbersome for code examples.

Most of the cookbook snippets have only one simple product (image, plot etc), so you don't gain a great deal by showing the results from each line in the notebook.

Additionally, however great notebooks are, they're not as handy for tasks that you need to perform repeatedly or for writing full length analysis scripts. In my opinion, using yt as a front end to more detailed analysis is one of its major strengths. If you take away the cookbook scripts, we lack examples of yt in python programs. 

The notebooks are also not quite as easy to use as a downloaded code snippet. 

Elizabeth



On Oct 23, 2013, at 7:23 PM, Brian O'Shea <bwoshea@gmail.com> wrote:

Hi Cameron,

For what it's worth, as a user of yt I find the current cookbook format to be incredibly useful.  I don't think notebooks would add to the utility - it's easy enough for me to download the script and load it into a notebook on my own machine if that's what I want to do.  It definitely seems that the challenges (and possible downsides) substantially outweigh the benefits, at least for me and my usage patterns.

--Brian



On Tue, Oct 22, 2013 at 4:13 PM, Cameron Hummels <chummels@gmail.com> wrote:
Hey everyone,

The documentation sprint is next Monday and Tuesday for those of you who want to participate.  I'll send out another email regarding that in the next day or so.

In preparation for that, though, I wanted to request input from the developer community on something related to the docs.

Right now, the cookbook page contains a lot of recipes for doing various things, and I think it is hugely beneficial to the community to maintain this (I personally use this page a lot too!).  However, with the advent of ipython notebooks over the last year, we are faced with a question: should we move toward incorporating more notebooks into our documentation, and specifically, do you we want to transfer the existing cookbook to a series of notebooks for each task?

Benefits:
--Portability: users can download an entire notebook for both viewing how it should work as well as being able to execute it locally on their own datasets
--Illustrative: Interim steps in a cookbook can produce output that can show up inside the notebook, instead of being a single script which generates an image/output at the end (as is the case in the current paradigm)
--Narrative: notebooks provide more space for narrating each step, instead of confining any narrative to comments in the recipe itself

Disadvantages:
--Work: it is going to take a decent amount of work to move all of the recipes over from the existing cookbook to individual notebooks
--Bulking of repo: In the current paradigm, images associated with each recipe are generated dynamically on the server by executing each script, thereby minimizing the number of files that need to be tracked by mercurial.  By moving to a notebook with images that are embedded in each notebook, we'd potentially increase the footprint of the repository substantially, especially if there were frequent updates of individual recipes.

I also like the yt bootcamp notebooks that Matt put together a year ago.  I think they are great for getting new users up to speed on how to use various aspects of the code.  Perhaps this notebook could make its way into the beginning of the cookbook for a more streamlined approach to the documentation?

So now is your chance to vote:

Move cookbook to ipython notebooks? +/- 0-1?

Move yt bootcamp to cookbook? +/- 0-1?

Comments?  Suggestions?

Cameron

--
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona

_______________________________________________
yt-dev mailing list
yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org


_______________________________________________
yt-dev mailing list
yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org


_______________________________________________
yt-dev mailing list
yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org