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

[Matthew Turk]

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