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

Tue Oct 22 17:59:47 PDT 2013

Ah, nice catch - I missed that link somehow.  runipy looks interesting...

Hopefully your message to IPython-dev will trigger some more "official"
discussion.

On Tue, Oct 22, 2013 at 5:52 PM, Nathan Goldbaum <nathan12343 at gmail.com>wrote:

> The issue you pasted led here:
> https://github.com/ipython/ipython/issues/1675
>
> Which led to here in the end: https://github.com/paulgb/runipy
>
> I'm not sure if there is an "official" way to do it, but runipy seems like
> it's worth looking into.
>
>
> On Tue, Oct 22, 2013 at 5:46 PM, Anthony Scopatz <scopatz at gmail.com>wrote:
>
>>
>> On Tue, Oct 22, 2013 at 7:38 PM, Chris Malone <chris.m.malone at gmail.com>wrote:
>>
>>> So I also thought there was a way to do this, but it looks like there
>>> isn't: https://github.com/ipython/nbconvert/issues/13
>>>
>>
>> I agree with pi here. Executing all while saving or converting is a bad
>> idea.
>>
>> However, a command line interface or a way from python to execute all
>> cells is really useful to have.
>>
>> Be Well
>> Anthony
>>
>>
>>
>>>
>>> The button for it is to evaluate all the cells.  Then you would need to
>>> save that ipynb, and run nbconvert on the completely evaluated notebook, as
>>> I understand.
>>>
>>> Chris
>>>
>>>
>>> On Tue, Oct 22, 2013 at 5:29 PM, Anthony Scopatz <scopatz at gmail.com>wrote:
>>>
>>>> On Tue, Oct 22, 2013 at 7:24 PM, Nathan Goldbaum <nathan12343 at gmail.com
>>>> > wrote:
>>>>
>>>>> If we keep the evaluated notebooks in the repo, we need to store the
>>>>> images since they're inlined as strings in the ipynb file.
>>>>>
>>>>> I'm not sure if it's possible to programatically evaluate all the
>>>>> cells in a notebook.  If we can do that, that's probably the way to go.
>>>>>
>>>>
>>>> This has to be possible.  There is a button for it =).  if not we
>>>> should complain / issue a PR until it is there.
>>>>
>>>> Be Well
>>>> Anthony
>>>>
>>>>
>>>>>
>>>>> Nathan
>>>>>
>>>>>
>>>>> On Tuesday, October 22, 2013, Chris Malone wrote:
>>>>>
>>>>>>  I'm not by any means an expert on this, but can't we do something
>>>>>> similar where each commit runs nbconvert on the ipynb to create static HTML
>>>>>> and images that are then pushed to the web?  I'm not sure I understand the
>>>>>> need to actually keep the images within the repo.  What am I missing?
>>>>>>
>>>>>> On Oct 22, 2013, at 4:24 PM, Nathan Goldbaum <nathan12343 at gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>> I know I originally suggested moving to notebooks, but upon further
>>>>>> reflection I think it might be too much of a pain for us to manage.  Given
>>>>>> that the notebooks would be pretty useless if they came down un-evaluated,
>>>>>> we would need to store many images in the docs repo.
>>>>>>
>>>>>> I think our current solution of static scripts along with a sphinx
>>>>>> plugin that gets executed in a docs build for every commit to the docs repo
>>>>>> is a good one.
>>>>>>
>>>>>>
>>>>>> On Tue, Oct 22, 2013 at 1: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
>>>>
>>>>
>>>
>>> _______________________________________________
>>> 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/20131022/d5955b14/attachment.html>