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

Nathan Goldbaum nathan12343 at gmail.com
Wed Oct 23 09:51:30 PDT 2013


It should be straightforward to generate downloadable .py scripts using
nbconvert on a recipe notebook.  The way I see it, on each page we will
present an evaluated notebook (sort of like the pyne documentation, e.g.:
http://pynesim.org/gallery/data_sources.html), along with links to
evaluated and unevaluated versions of the notebook and an nbconverted
python script version of the notebook.

Brian and Matt, does that satisfy your concerns?

Another big win with this is that it becomes straightforward to version
other notebooks we track.  For example, instead of hosting the bootcamp
notebooks on the yt hub, they could become part of the documentation repo
and could be run with every documentation commit (possibly every commit to
the yt repo?).  This way we could ensure that the bootcamp notebooks are
always up to date.

In the past there was also some discussion of hosting 3.0 example notebooks
that update whenever we commit to the 3.0 repo as a lightweight form of
answer testing.  Again, it would be straightforward to automate this using
these new tools.

I'm going to try to come up with a proof of concept for a sphinx plugin
that does all of this sometime this weekend.  Even if we decide not to use
it for the cookbook, I think it will have utility elsewhere.

-Nathan


On Wed, Oct 23, 2013 at 7:52 AM, Cameron Hummels <chummels at gmail.com> wrote:

> After the discussion pointing to using the runipy utility, which solves
> all of the server-side problems, it seemed to me that this was a slam dunk
> on switching to notebooks.  I still think it is easy with a cookbook made
> of notebooks to grab a snippet of code and use it on the client side, just
> using copy/paste (as most people do with the existing code snippets).  To
> replicate the existing format of the code snippets would be trivial as
> well.  When we're generating the notebooks, you have the option of saving
> as a notebook, or saving it as straightup python code.  We could save both
> versions of the code.  Then on the cookbook, we display our series of
> recipes showing the notebook inline, but then presenting a link to each as
> a notebook as well as the raw python code.  It seems like that covers all
> of our bases, as long as we can display the notebooks inline in sphinx.  It
> was my understanding that this was possible with runipy and a sphinx
> plugin.  That said, i'm not tied to this idea, it just seemed to have so
> many advantages to the user base and with the discovery of runipy, almost
> no disadvantages.
>
> I'm -1 on having some items in the cookbook be for notebooks and some be
> for code snippets.  I think that kind of heterogeneity is confusing.
>
>
>
>
> On Wed, Oct 23, 2013 at 6:17 AM, Matthew Turk <matthewturk at gmail.com>wrote:
>
>> Hi all,
>>
>> After following this discussion, I am kind of in agreement with Brian.  I
>> think having notebooks would ease our job, but would also make it a bit
>> harder for people reading the docs to get at little snippets, particularly
>> if they are broken up with non-commented lines of text.  Perhaps what would
>> be better would be organizing the cookbooks somewhat nicer, and moving
>> longer-form items to notebooks.
>>
>> As long as we're on the topic, I have been working a little bit on docs
>> for yt-3.0.  I think we may want to consider the following things for the
>> 3.0 docs:
>>
>>  * Removing the orientation and just providing the bootcamp (which will
>> be extended), sticking the helpful links in other sections
>>  * Removing the workshop materials, as the are not 100% relevant anymore
>> (and indicating what is and is not relevant is tricky)
>>  * Reworking the field list, although I don't yet know in what way.
>>   * Moving "loading data" to the top level.  (I have done this already,
>> as I think it needs to be a lot more prominent.)
>>
>> -Matt
>>
>>
>> On Wed, Oct 23, 2013 at 6:23 AM, Brian O'Shea <bwoshea at gmail.com> wrote:
>>
>>> Hi Cameron,
>>>
>>> For what it's worth, as a user of yt I find the current cookbook format
>>> to be incredibly useful.  I don't think notebooks would add to the utility
>>> - it's easy enough for me to download the script and load it into a
>>> notebook on my own machine if that's what I want to do.  It definitely
>>> seems that the challenges (and possible downsides) substantially outweigh
>>> the benefits, at least for me and my usage patterns.
>>>
>>> --Brian
>>>
>>>
>>>
>>> On Tue, Oct 22, 2013 at 4: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
>>
>>
>
>
> --
> 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/20131023/b3147240/attachment.html>


More information about the yt-dev mailing list