[yt-dev] yt docs hangout 10:00 AM PST tomorrow Was: Prep for 2.4

Matthew Turk matthewturk at gmail.com
Tue Jul 10 08:48:18 PDT 2012


Here's a build of the current state of the yt-doc repository:

http://yt-project.org/docs/2.4/

-Matt

On Mon, Jul 9, 2012 at 4:50 PM, Nathan Goldbaum <goldbaum at ucolick.org> wrote:
> Hi all,
>
> Just a reminder that we're having a hangout tomorrow at 10:00 AM to discuss the docs reorganization and prep for the 2.4 release.
>
> Cheers,
>
> Nathan
>
> On Jul 8, 2012, at 5:30 AM, Britton Smith wrote:
>
>> I think Nathan's got the right idea in rearranging some of the sections.  I think the issue with the "Advance yt usage" subsection is that it has no cohesive theme and so finding what you're looking for in there is difficult.  In looking through the topics covered, I think most of them could find new homes either as sections of their own a level up or withing other categories.  I would be very interested in discussing this in the hangout if there are people interested in working specifically on this.
>>
>> Britton
>>
>> On Sat, Jul 7, 2012 at 11:10 PM, Nathan Goldbaum <goldbaum at ucolick.org> wrote:
>> Hi Matt,
>>
>> Overall I like the way the docs are organized now.  Reducing the number of API reference pages should also help fix the proliferation of search results in the docs.  I also really like having links to all of the reference information on the front page.
>>
>> However, I have two suggestions that I think will make the organization a bit clearer.  First, we should split up the panel of buttons on the right hand side into two sections, 'narrative docs' and 'reference'.
>>
>> Second, I think we should collapse the Everyday yt, Advanced Usage, and Getting Involved sections into two new sections: Using yt and the Developer's Guide.  A lot of the material in the Advanced usage category is actually not so advanced (installing yt), or is reference information for the internal api that belongs in the developer's guide.
>>
>> Maybe we should also record a screencast to highlight some of the new functionality so that we can link to it in the announcement e-mail.
>>
>> I'm excited to help get this release out the door :)
>>
>> -Nathan
>>
>> On Jul 7, 2012, at 7:49 PM, Matthew Turk wrote:
>>
>> > Hi all,
>> >
>> > I'm definitely game for trying to finish this up, starting with a
>> > hangout and then doing some coordinated work in IRC.  Unfortunately I
>> > am unable to lock down precisely what my schedule for next week is, so
>> > perhaps it would work best if we picked a time and I will do my best
>> > to join.  Would Tuesday morning, California time, work?  Say, around
>> > 10AM?
>> >
>> > John (and everyone else) -- it would be really, really helpful if we
>> > could tackle two major things.
>> >
>> > 1) Every function or object in yt.mods should have *at least* a
>> > one-line summary docstring.  The biggest omissions I see are
>> > BinnedProfile[12]D, parallel_objects, a few of the functions from
>> > image_writer.py, and (the hugest) the TimeSeries object and its
>> > methods.
>> > 2) We need simple *and* complex recipes that use the time series
>> > functionality.  In fact, recipes for these operations can/should be
>> > added to the source/cookbook directory in yt-doc:
>> >
>> > * very simple time series examination using the time series object
>> > * calculating radial velocity with bulk_velocity subtracted off
>> > * saving data to disk from profiles
>> >
>> > And for the https://bitbucket.org/yt_analysis/cookbook repository:
>> >
>> > * a field that uses field_parameters
>> > * a complex multi-plot
>> > * a complex set of profile plots with nice thick or varying line styles
>> >
>> > --
>> >
>> > I've tried rearranging a few things in the docs, and put up a
>> > temporary build here:
>> >
>> > http://yt-project.org/docs/2.4/
>> >
>> > The major visual/organization changes:
>> >
>> > * Bring all the reference material to the top level
>> > * Tables all have consistent widths
>> > * API docs all happen on one page ( http://yt-project.org/docs/2.4/api.html )
>> >
>> > What do you think?
>> >
>> > And, one thing that is a bit dissatisfying is that people don't
>> > necessarily know in advance what counts as "every day yt" or "advanced
>> > yt" or "analysis modules."  How do we address that?  Do we flatten, do
>> > we change names, etc?
>> >
>> > Thanks everybody -- it's really awesome that we have so much energy
>> > for documenting!  Let's push forward.  Incidentally, not only do we
>> > have some really awesome impressive features in this release, we've
>> > had 839 changesets since the last merge-to-stable (2.3 release.)
>> > That's about 14% of the total number of revisions in the repository.
>> >
>> > -Matt
>> >
>> > On Sat, Jul 7, 2012 at 9:55 AM, John ZuHone <jzuhone at gmail.com> wrote:
>> >> Matt,
>> >>
>> >> Anything specific you'd like me to work on?
>> >>
>> >> John ZuHone
>> >> Laboratory for High-Energy Astrophysics
>> >> NASA/Goddard Space Flight Center
>> >> 8800 Greenbelt Rd., Code 662
>> >> Greenbelt, MD 20771
>> >> (w) 301-286-2531
>> >> (m) 773-758-0172
>> >> jzuhone at gmail.com
>> >> john.zuhone at nasa.gov
>> >>
>> >> On Jul 6, 2012, at 7:03 PM, Matthew Turk <matthewturk at gmail.com> wrote:
>> >>
>> >>> Hi all,
>> >>>
>> >>> A few of us have been working on documentation in preparation for
>> >>> releasing yt 2.4.  I believe docs are the major change at this point,
>> >>> and once we have those in line we can pull the trigger.  The items
>> >>> below still need to be handled, and we'd really appreciate anybody
>> >>> that wants to pitch in.  The doc repository is at
>> >>> https://bitbucket.org/yt_analysis/yt-doc .  Please feel free to add
>> >>> items, edit existing docs, remove cruft, and whatever else seems
>> >>> appropriate.
>> >>>
>> >>> 1) Every single function or class imported in yt.mods needs to have at
>> >>> least a simple docstring that summarizes what it does.  I'd prefer
>> >>> these all be of the numpy docstring standard (see
>> >>> docs/example_docstring.rst)
>> >>>
>> >>> Can a few volunteers examine the stuff in yt/mods.py and see if they
>> >>> can help out adding docstrings?
>> >>>
>> >>> 2) What used to be "cookbook examples" in the docs are being
>> >>> transformed into "simple scripts," and cookbook scripts are being
>> >>> pulled out and put in a different place (you can see this in the
>> >>> yt_analysis/cookbook repo, which will have something like this:
>> >>> http://yt-project.org/cookbook/ ) .  The simple scripts are being
>> >>> converted to use the more complex datasets from the workshop datasets.
>> >>> Each will then be included manually.  Nathan and I are handling
>> >>> these.
>> >>>
>> >>> If anyone wants to take a crack at adding more *simple* scripts to
>> >>> both source/cookbook/ as .py files, that would be helpful.  We could
>> >>> use things like "getting enclosed mass" and "how to save out profiles
>> >>> to disk" and "setting colorbars" and whatnot, but nothing too complex.
>> >>>
>> >>> 3) The workshop page still has to be added -- this is basically a
>> >>> version of this section: http://yt-project.org/workshop2012/#workshop
>> >>> where we have a list
>> >>>
>> >>> 4) The narrative docs should be converted to reference PlotWindow,
>> >>> rather than PlotCollection (wherever possible, although for now
>> >>> callbacks do not work with PlotWindow).  I think Nathan might tackle
>> >>> this.
>> >>>
>> >>> 5) The Volume Rendering docs need to be updated to be, well, in line
>> >>> with current best practices.
>> >>>
>> >>> 6) Low-level data inspection docs should be added.
>> >>>
>> >>> 7) ...anything else?
>> >>>
>> >>> =
>> >>>
>> >>> Here are the remaining tickets:
>> >>>
>> >>> https://bitbucket.org/yt_analysis/yt/issues?status=new&status=open&milestone=2.4
>> >>>
>> >>> and the current draft of the changelog:
>> >>> http://paste.yt-project.org/show/MfdV3E8s2H7pc1pC3mVp/  .  If you have
>> >>> additions, please feel free to reply with them!
>> >>>
>> >>> I'm going to prepare some (html) slides that lay out new features,
>> >>> describe changes in behavior, and have examples.
>> >>>
>> >>> Does anyone have any comments or suggestions?
>> >>>
>> >>> -Matt
>> >>> _______________________________________________
>> >>> 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
>> >
>> >
>> >
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>> !DSPAM:10175,4ff97d55189991325623656! _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>> !DSPAM:10175,4ff97d55189991325623656!
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org



More information about the yt-dev mailing list