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

[Anthony Scopatz]

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