Adding tutorials to xarray documentation splash page

[orianac]

I was looking at the dask splash page and I noticed it has some binder tutorials which are really nice:

As a novice user of xarray, I thought it could be nice to add something like that to the readthedocs welcome page. I know that @jhamman already has some little tutorials prepared so it'd just be a matter of:

1. Making sure an appropriate tutorial is selected,
2. Getting the tutorial in the right place, and
3. Linking the tutorial into the xarray documentation.

I'd be happy to try to add this piece, though it might take me a little while to get up to speed.

[jhamman]

Thanks @orianac for posting this as an issue. I agree something like this would be really nice to showcase. I'm curious how others think this should be organized. My tutorials () are pretty basic and may not be the most impressive way to "wow" new users. I'm thinking we may be able identify 2 or 3 main use cases / patterns and build out some examples from there. Thoughts?

[shoyer]

I agree that advertising tutorials prominently would be a real win. The current xarray documentation leans towards being an authoritative reference, which is less helpful for new users.

Throwing out some ideas for :

• Xarray for geoscience users
  • load/save netCDF data
  • calculate climatologies
  • regridding/interpolation? maybe using xESMF?
• Xarray for general data analysis
  • show how xarray does alignment like pandas
  • show how xarray does broadcasting (sort of like numpy)
  • show how xarray works easily with numpy and pandas
• Xarray for parallel computing
  • show how everything scales up with dask?

[orianac]

Also, showcasing the nifty plotting functionality could be nice. As someone who spends so much time making plots, proof that it's easy to just do .plot() could be very persuasive for trying out xarray!

[jhamman]

Calling volunteers to help develop some of these tutorials? I'll volunteer to setup a binder ready repository and review any notebooks that get put together.

[jhamman]

see https://github.com/xarray-contrib/binder-tutorial for a start here. I opened specific issues for the three notebooks @shoyer identified.

[JiaweiZhuang]

Just FYI, I wrote a xarray tutorial at https://github.com/geoschem/GEOSChem-python-tutorial with Binder enabled.

I taught it in several GEOS-Chem user workshops and it turned out to work pretty well. Most of our users only know MATLAB&IDL, so I have to teach Python from scratch and then introduce xarray. I found IDL vs xarray a good example to "wow" new users. Manipulating NetCDF files is a real pain in those old languages. There is also a chapter on xESMF, of course😉

I use GEOS-Chem data as an example, but most contents are quite general and should be useful for other geoscience users.

[rabernat]

I plan on getting this started during the Xarray SciPy sprint on Saturday.

I would like to see a high-level tutorials heading in our documentation, like this

(I'm not proposing to eliminate the User Guide, I just suck at annotating screenshots.)

I think the "example" page should be refactored into more verbose tutorials. The examples are a bit stale.

Ideas? Feedback?

[dcherian]

I think we should combine the example notebooks with "gallery"

[rabernat]

@dcherian - in Pangeo we are using sphinx-nbexamples instead of sphinx-gallery. I like it more becuase you provide the examples as notebooks, rather than scripts, which is better suited to longer, more detailed examples.

How would you feel about refactoring the gallery to use sphinx-nbexamples, and then using this for the tutorials as well?

[dcherian]

I think that sounds great and compatible with the binder ideas on this thread

[rabernat]

FYI in the scipy19-docs branch we are now using nbsphinx. I couldn't get sphinx-nbexamples to work.