[yt-dev] Request comments/vote on use of notebooks in yt docs

[Chris Malone]

I'm +1 on this, with the possibility of providing also just the .py files
from nbconvert for those that won't/can't use notebooks.

Chris


On Thu, Oct 24, 2013 at 12:28 PM, Sam Skillman <samskillman at gmail.com>wrote:

> 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 at 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 at 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 at 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
>>> http://chummels.org
>>>
>>> _______________________________________________
>>> yt-dev mailing list
>>> yt-dev at lists.spacepope.org
>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>
>>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>
> _______________________________________________
> 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/20131024/6bc0c82b/attachment.html>