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=…
--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=…
.
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
<https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=…>
--
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org
New issue 704: update all frontend api links for currently supported codes
https://bitbucket.org/yt_analysis/yt/issue/704/update-all-frontend-api-link…
Cameron Hummels:
right now when you generate the api docs, it generates frontend docs for:
enzo, orion, flash, chombo, and ramses.
when it should generate frontend api docs for:
enzo, orion, flash, chombo, castro, pluto, stream, nyx, athena, gdf, and orion
Responsible: MatthewTurk
New issue 703: describe how to get sample datasets
https://bitbucket.org/yt_analysis/yt/issue/703/describe-how-to-get-sample-d…
Cameron Hummels:
have one single location explaining how to get the sample datasets (and link to it in all of the other mentions of it). also explain how setting up a line in their config file will allow them to execute it without being in the local sample data directory.
potentially this line in the config file annotation would go in the config file explanation.
New issue 701: Documentation improvements
https://bitbucket.org/yt_analysis/yt/issue/701/documentation-improvements
gsiisg:
Some might be nitpicking or personal preference, but some are just plain typos. I was not able to read through the entire doc in one sitting, so I did not get to the later sections below Halo Profiling. Hopefully these are not all already identified errors that others caught.
From
G.S.
yt Bootcamp: A Worked Introduction:
-> Data Inspection:
"This section can be skipped!" If someone added comments on what each command line demonstrates, this section would not have to be skipped. Seems like useful things to know like how to access the data within grids, printing out min/max values of each field, but not sure about the lines and their purpose:
print (g2.Parent.child_mask == 0).sum() * 8
print g2.ActiveDimensions.prod()
-> Simple Visualization
zoom I think is self explanatory, but I think a short description like
p.pan_rel((0.1, 0.0))
"this pans the camera relative to the previous location (x,y) amount", will be helpful.
-> Data Objects and Time Series:
No units associated with three line graphs plotted.
-> Derived Fields and Profiles:
to show how LaTeX friendly the units are, we can change the units of
"Trex/s" to "Trex s$^{-1}$"
and actually print out the units in the subsequent graph that use the field. Again missing units in the graphs.
The yt Cookbook
-> A Few Complex Plots
Under "Projecting Off-Axis with a Colorbar" there's the following note:
"Please note that this same write_projection function will work with a volume rendering to generate a colorbar in the same fashion."
This ought to have an example, I think showing a volume rendering with a colorbar will be extremely useful. Maybe it is in the latest version but I do not recall from the dev, or 2.5 version of the docs.
Visualizing Data
-> Plot Modification Mechanisms:
- Thanks to whom ever that put in the available callbacks, this is a huge improvement from previous version of the doc.
-> Using the Manual Plotting Interface:
- Should there be a example of how one may save an .PNG/.JPG and use it in an .EPS file as per the EPS writer tutorial from the workshop material here, or is that functionality being phased out? At least in ApJ they require all graphs to be in EPS format, but maybe since they're no longer so strict on the file size, outputting it in native eps would be fine. However, EPS looks pixelated and blurry when you zoom in to look at individual pixels, PNG looks sharp. Or stick this in the "Generating Processed Data" section, which might be a better place.
-> Volume Rendering:
"As of yt 2.4, this code is threaded using OpenMP. Many of the commands (including snapshot) will accept a num_threads option."
- An example of the commands using this would be helpful, and a hybrid OpenMP+MPI one as well.
"See transfer_functions."
- link missing to transfer_functions
"Unfortunately, due to issues spherical-projection issues,"
- typo too many "issues"
- HEALPix graphic should have LaTeX label, currently it shows "g/cm^2", should switch to "g cm$^{-2}$" or at least "g/cm$^2$"
- Consistency in using "HEALPix" or "HEALpix"
- "using the imshow command:"--> using the imshow() command:
Analyzing Data
-> Using and Manipulating Objects and Fields
- typo "only regions that posses certain properties are of interest." - should be "possesses"
-> Examining and Manipulating Particles
- typo "For simulations only including dark matter particles" -> "including only"
-> Parallel Computation With YT
- typo "if you wanted it to run in parallel on 16 cores (you can always the number of cores you want to run on)"--> you can always select the number of cores
--> Analysis Modules
---->Halo Finding
- parallel HOP is published so no need to link the ArXiv pre-print at "http://adsabs.harvard.edu/abs/2010ApJS..191...43S"
How to Develop yt
"Numpy is to be imported as na not np. While this may change in the future, for now this is the correct idiom."
- I thought this was changed long ago to np now
New issue 698: Make "SlicePlot", "ProjectionPlot", etc show up How to Make Plots TOC
https://bitbucket.org/yt_analysis/yt/issue/698/make-sliceplot-projectionplo…
Britton Smith:
The SlicePlot, ProjectionPlot, etc section headers should be promoted so that they show up in the Visualizing Data table of contents.
Responsible: ngoldbaum