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

[Anthony Scopatz]

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