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:
You can view this version of the docs looks here (minus the api docs and the bootcamp renderings):
THREE TIERS OF INTERACTING WITH YT
--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.
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.