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@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@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@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@gmail.com john.zuhone@nasa.gov
On Jul 6, 2012, at 7:03 PM, Matthew Turk <matthewturk@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@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
!DSPAM:10175,4ff97d55189991325623656! _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
!DSPAM:10175,4ff97d55189991325623656!
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org