[yt-dev] Documentation Sprint

Matthew Turk matthewturk at gmail.com
Wed Oct 30 07:35:29 PDT 2013 

Hi Cameron,

Thank you for such hard work leading this initiative -- and thanks to
everyone else who participated.  Nathan, I love the notebook sphinx
extensions you came up with!

On Wed, Oct 30, 2013 at 4:26 AM, Cameron Hummels <chummels at gmail.com> wrote:
> Hey everyone,
>
> We finished up the doc sprint today.  I think we made some big improvements
> to the doc base in the last two days with help from: Sam Skillman, Geoffrey
> So, Nathan Goldbaum, John Zuhone, Jeff Oishi, Britton Smith, Matt Turk, and
> me.  Thanks everyone!  But we're not done with everything yet.  By my tally,
> everyone still has a task to complete, and there are still some open tickets
> on the bitbucket docs issues list.  In this email, I'll try to summarize
> what we did, what remains to be done, and what the timeline forward is.
>
> First of all, the latest docs exist in my PR here:
> https://bitbucket.org/yt_analysis/yt-doc/pull-request/110/updates-to-docs-after-day-one-of-the-doc/
>
> There is a build of this available for viewing here:
> http://green.as.arizona.edu:8080
>
> ACCOMPLISHED
> --Restructured the doc layout to be more hierarchical, so that now all of
> the docs fall into the following categories: install/, help/, bootcamp/,
> cookbook/, development/, examine/, visualize/, analyze/, and reference/.
> --Restructured the top-level page to reflect this, resulting in a much
> simpler and cleaner starting point.
> --Added support for embedded notebooks, embedded executed scripts, and
> embedded notebook snippets in the docs which get executed and built
> dynamically with the docs.
> --Updated what codes are supported in 2.x (removed support for gadget,
> ramses and art, since these don't work well in 2.x)
> --Updated the installation instructions
> --Moved the bootcamp from its own repository into the docs as the main
> introduction to the code using embedded notebooks.
> --Updated the "How to get help" to be "how to solve problems" with several
> suggestions that one can do on their own before turning to the mailing list.
> --Split the cookbook into Example Scripts and Example Notebooks (longer
> demonstrations of more complex functionality).
> --Updated the "How to Make Plots" and "Plot Modification" parts of the
> visualization docs making extensive use of the new embedded scripts and
> embedded notebook snippets.  Looks great!
> --Added a section on how to make SZ synthetic observations on one's datasets
> using the new embedded notebook
> --Getting rid of the old workshop lessons
> --Removing the bitbucket wiki, since it contained outdated and conflicting
> redundant information from the docs
> --Numerous updates and typo fixes
>
> YET TO BE FINISHED
> (see open documentation issues here:
> https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new
> )
> --Explain use of CuttingRegion/FieldCuts -- Britton
> --Write up ProfilePlot docs -- Britton
> --Make PhasePlot work in yt and document it -- Matt and Britton
> --Introduce how to use a notebook -- Nathan
> --Update VR docs -- Sam
> --Make a VR notebook with a great example -- Sam
> --Demonstrate how to bring in arbitrary grid datasets into the code -- John
> --Purge, fix, move dangling links in the code from the restructure --
> Cameron
> --Describe how to export to sketchfab -- Matt
> --Add section in developer docs on "How to dig into the source" --Cameron
> --Describe how to get the sample datasets and set up test_dir in config.
> --Document how to do VR with two fields (cookbook)
> --Update docs for command-line arguments
> --Document cosmology units
>
> I think we need to finish these things before the release of 2.6.  I think
> if people continue to work on these issues with the same momentum we've had
> the last couple of days, we'll get this finished in the next week.
>

Because 2.6 is -- hopefully -- the last *major* yt release in the 2.x
line, I would like to consider the list you have identified above as
"blockers" for a release.  This means delaying past November 1st.  In
particular, the profileplot and phaseplot absolutely need to be
finished, and Britton and I have come up with a plan for finishing
that off.  The reason I say this is that the ProfilePlot and PhasePlot
remove essentially the last vestige of needing a PlotCollection, and
that would be a nice close to the 2.X line of development.

Great work, everyone.

-Matt

> Overall, I think the docs are looking a lot better at this point.  Let us
> know if you have any additional comments/suggestions.  Thanks again to those
> of you who put in a lot of hard work the last couple of days!
>
> Cameron
>
>
> On Mon, Oct 28, 2013 at 6:16 PM, Cameron Hummels <chummels at gmail.com> wrote:
>>
>> Hey everyone,
>>
>> This is a status update after day one of the doc sprint.  We had a good
>> turnout with Matt Turk, Sam Skillman, John Zuhone, Jeff Oishi, Nathan
>> Goldbaum, and myself present.  We were able to get a lot done, some
>> synchronously, some asynchronously, over the course of the day.
>>
>> Work has begun on restructuring the docs to make them more easily
>> navigable.  The front page has been cleaned up to have a limited number of
>> top-level options for users.  The installation page has been updated.  The
>> cookbook repository has been merged into the docs inline so that new users
>> can view (or execute) that as their introduction to the functionality of yt.
>> Minor changes have occurred on the help pages and the developer pages.
>> Significant effort has gone into making the docs more succinct and having
>> fewer overlap points (where some concept is explained more than once).  The
>> workshop materials were removed and many of the former top-level directories
>> (e.g. advanced) have been split up and redistributed into the other code
>> directories.  A new sample dataset was added to the yt-project.org/data site
>> by Nathan of one of his high-res isolated galaxy sims--it's almost 3 GB, but
>> it's a beautiful dataset for demonstrating some cool functionality with real
>> data.
>>
>>
>> CURRENT VERSION OF CODE
>> I've issued a PR to the yt-doc repo with many of these changes here:
>>
>> https://bitbucket.org/yt_analysis/yt-doc/pull-request/110/updates-to-docs-after-day-one-of-the-doc/commits
>>
>> You can view this version of the docs looks here (minus the api docs and
>> the bootcamp renderings):
>> http://green.as.arizona.edu:8080/
>>
>>
>> THREE TIERS OF INTERACTING WITH YT
>> We seemed to settle on grouping yt functionality into 3 tiers: visualizing
>> data, analyzing data, and examining data (accessing it at a low level).  Sam
>> Skillman made a cool illustration of this here:
>> https://docs.google.com/drawings/d/15aWmO71uHaxjx0qK5bMGxHir9wPI27Cgk-qG03Y00nc/edit
>> .  The plan is to have the docs reflect this hierarchy and to have it show
>> up in the introductory statements on the front page.
>>
>>
>> CURRENT TASKS
>> --Nathan - Creating a set of notebooks to demonstrate how to use the plot
>> window and plot modifications effectively.  This will update the entire
>> plotting interface portion of the docs.  Also, create an introduction to how
>> to use notebooks from scratch.
>> --Jeff & Sam - Writing a notebook demonstrating how to use it for doing
>> real science, not just merely as a toy.
>> --Cameron - Going over the top-level docs with a fine-toothed comb looking
>> to update/clarify.  Restructuring the hierarchy of docs.
>> --John - Updating the Athena frontend; Documenting SZ analysis and
>> particle trajectories in the analysis modules section.
>> --Matt - Restructuring the hierarchy of docs.  Purging out-of-date
>> information.  Picking a new theme for the docs.
>>
>> But there is still a lot left to do.  For those of you who want to
>> participate but don't yet know how you can assist, you can do a few things.
>> --Look over the docs and see if you find anything that needs fixing,
>> pruning, updating, etc.  Add an issue in the yt_analysis/yt repo and tag it
>> with documentation, so we know to fix it.  Or create an issue and fix it
>> yourself and PR it.  Really, the docs just need some attention to clean them
>> up.
>> --Look at the existing documentation issues on bitbucket.  Address one of
>> them.
>>
>> COOKBOOK
>> I think we settled on a solution to the notebook vs script debate.
>> Continue to use scripts for the simpler tasks in the cookbook and use
>> notebooks for more complex examples.  Right now I've split the cookbook into
>> Example Scripts and Example Notebooks for this task.  Tomorrow will be spent
>> adding more coding examples to both of these subdivisions.
>>
>> GOALS FOR TOMORROW
>> Finish restructuring the docs.  Add lots more recipes (both notebook and
>> scripts) to the cookbook.  Address more of the issues from the bb list.
>>
>> If you want to join us, come by IRC or google+ at 8amPST tomorrow, and
>> we'll put you to good use.
>>
>> Cameron
>>
>>
>> On Sat, Oct 26, 2013 at 9:40 AM, Britton Smith <brittonsmith at gmail.com>
>> wrote:
>>>
>>> Hi Cameron,
>>>
>>> Thanks for organizing this!  This will be very useful I think.  I will be
>>> traveling for most of Monday during the time of the sprint but should be
>>> able to participate on Tuesday.  It would be useful if you could provide a
>>> short summary of the events of the first day for those of us who can only
>>> join in on the second day.  Thanks again for doing this.  See you all there.
>>>
>>> Britton
>>>
>>>
>>> On Thu, Oct 24, 2013 at 2:16 AM, Cameron Hummels <chummels at gmail.com>
>>> wrote:
>>>>
>>>> Hey everyone,
>>>>
>>>> Next Monday and Tuesday we will be having a documentation sprint to try
>>>> to beef up the yt docs (and docstrings) before the final release of the 2.x
>>>> branch when development (and documentation) will switch over to the 3.0
>>>> branch.  All developers are welcome to attend/participate for as much time
>>>> as they can spare.
>>>>
>>>> I know documentation isn't always glamorous, but I think this will be
>>>> pretty fun.  Furthermore, I think this will be very beneficial to the
>>>> community, in that it will be fewer frustrated users, fewer questions on IRC
>>>> and the mailing list, and better understanding for everyone of all the
>>>> features and functionality of the codebase!
>>>>
>>>> We will be meeting up as a Google + hangout over the course of those two
>>>> days, with periodic "check-in" meeting times to make sure everyone is on the
>>>> same page (see below for schedule).  Yes, I know it is early for Pacific
>>>> Coasters on a Monday @ 8am, but you can meet for a few minutes from your bed
>>>> without your camera turned off if need be.  We all know that people have
>>>> meetings and need to eat and such, so you are not required to be in the G+
>>>> hangout constantly.  That said, people are encouraged to remain in the G+
>>>> hangout throughout both days for fast turnover time if they have
>>>> questions/discussion or want to work on something new.  Documentation tasks
>>>> will be identified so that attendees can volunteer for them at the various
>>>> check-in meetings.  This way, individuals can work on these tasks
>>>> semi-autonomously.  The various things I think we should aim to accomplish
>>>> include:
>>>>
>>>> --Add documentation for features that are currently undocumented in the
>>>> yt codebase.
>>>> --Add documentation for new features from yt 2.5 to present (in
>>>> docstrings, cookbooks, and narrative docs as applicable).
>>>> --Fulfill the tasks identified in the BitBucket Documentation Issues
>>>> List:
>>>>
>>>> https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new
>>>> --Remove outdated information from the docs.
>>>> --Pare down multiple locations of how to do individual tasks, so as to
>>>> make maintainability easier.
>>>> --Fix any typos or mistakes in the content.
>>>>
>>>> SCHEDULE
>>>> Monday
>>>> --8am PST/11am EST: Initial meetup in G+ to discuss the goals of the
>>>> sprint and to layout the specific individual tasks which need to be
>>>> accomplished.  I'll include a template for a docstrings example, a template
>>>> for a cookbook example, and an example of a good narrative docs section.
>>>> Developers will choose what task they want to work on.  Meeting should take
>>>> 30-60 minutes.
>>>> --11am PST/2pm EST: Status check, and reshuffling of projects as needed.
>>>> 15 minutes.
>>>> --2pm PST/5pm EST: Status check and conclusion for the day. 15 minutes.
>>>>
>>>> Tuesday
>>>> Same schedule as Monday.
>>>>
>>>> WHAT I NEED FROM YOU
>>>> Please write back to this email saying whether or not you're going to be
>>>> attending any/all of the sprint.  That way, I can invite you personally to
>>>> the google docs hangout to join up.  I may try to make this hangout "on-air"
>>>> so that it is recorded, and so if we go above the 10-person limit, those
>>>> unable to fit in the hangout can watch it streaming live.
>>>>
>>>> Before Monday, please think for a few minutes about things that you may
>>>> have noticed in the past that were lacking from the documentation, but at
>>>> the time you found them you didn't have time to fix.  If you identify
>>>> anything, please mark it down as a documentation task in the bitbucket issue
>>>> tracker so that we know to work on it next week:
>>>> https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new
>>>> . We will be using this as our main means of tracking what gets accomplished
>>>> during the sprint.  I encourage you to look at the docs as well to look for
>>>> ways they can be improved.
>>>>
>>>> Thanks everyone, and I look forward to meeting with you next week!
>>>>
>>>> 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
>>>
>>
>>
>>
>> --
>> Cameron Hummels
>> Postdoctoral Researcher
>> Steward Observatory
>> University of Arizona
>> http://chummels.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
>

More information about the yt-dev mailing list