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

Nathan Goldbaum nathan12343 at gmail.com
Tue Oct 22 17:52:36 PDT 2013


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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20131022/defb14f0/attachment.htm>


More information about the yt-dev mailing list