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

Nathan Goldbaum nathan12343 at gmail.com
Tue Oct 22 16:24:50 PDT 2013


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


More information about the yt-dev mailing list