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

[Chris Malone]

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

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