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

Chris Malone chris.m.malone at gmail.com
Tue Oct 22 17:18:47 PDT 2013


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


More information about the yt-dev mailing list