Add sphinx-gallery to the docs (#1419)

* Add sphinx-gallery to the docs

* Whats new

* Move to examples

* Rename to recipes

Author: fmaussion

Diff for: doc/Makefile

@@ -48,6 +48,7 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf generated/*
+	rm -rf auto_gallery/
 
 .PHONY: html
 html:
@@ -67,6 +68,12 @@ singlehtml:
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
+.PHONY: html-noplot
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 .PHONY: pickle
 pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

Diff for: doc/conf.py

@@ -91,12 +91,18 @@
     'numpydoc',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx_gallery.gen_gallery',
 ]
 
 extlinks = {'issue': ('https://github.com/pydata/xarray/issues/%s', 'GH'),
             'pull': ('https://github.com/pydata/xarray/pull/%s', 'PR'),
             }
 
+sphinx_gallery_conf = {'examples_dirs': 'gallery',
+                       'gallery_dirs': 'auto_gallery',
+                       'backreferences_dir': False
+                       }
+
 autosummary_generate = True
 
 numpydoc_class_members_toctree = True

Diff for: doc/environment.yml

@@ -15,3 +15,5 @@ dependencies:
   - netCDF4=1.2.5
   - hdf4=4.2.12  # temporary install to get netCD4 working (GH1106)
   - cartopy=0.14.3
+  - pip:
+    - sphinx-gallery

Diff for: doc/examples.rst

@@ -8,3 +8,4 @@ Examples
     examples/weather-data
     examples/monthly-means
     examples/multidimensional-coords
+    auto_gallery/index

Diff for: doc/gallery/README.txt

@@ -0,0 +1,5 @@
+.. _recipes:
+
+Recipes
+=======
+

Diff for: doc/gallery/plot_cartopy_facetgrid.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""
+==================================
+Multiple plots and map projections
+==================================
+
+Control the map projection parameters on multiple axes
+
+This example illustrates how to plot multiple maps and control their extent
+and aspect ratio.
+
+For more details see `this discussion`_ on github.
+
+.. _this discussion: https://github.com/pydata/xarray/issues/1397#issuecomment-299190567
+"""
+
+import xarray as xr
+import cartopy.crs as ccrs
+import matplotlib.pyplot as plt
+
+# Load the data
+ds = xr.tutorial.load_dataset('air_temperature')
+air = ds.air.isel(time=[0, 724]) - 273.15
+
+# This is the map projection we want to plot *onto*
+map_proj = ccrs.LambertConformal(central_longitude=-95, central_latitude=45)
+
+p = air.plot(transform=ccrs.PlateCarree(),  # the data's projection
+             col='time', col_wrap=1,  # multiplot settings
+             aspect=ds.dims['lon']/ds.dims['lat'],  # for a sensible figsize
+             subplot_kws={'projection': map_proj})  # the plot's projection
+
+# We have to set the map's options on all four axes
+for ax in p.axes.flat:
+    ax.coastlines()
+    ax.set_extent([-160, -30, 5, 75])
+    # Without this aspect attributes the maps will look chaotic and the
+    # "extent" attribute above will be ignored
+    ax.set_aspect('equal', 'box-forced')
+
+plt.show()

Diff for: doc/gallery/plot_colorbar_center.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""
+==================
+Centered colormaps
+==================
+
+xarray's automatic colormaps choice
+
+"""
+
+import xarray as xr
+import matplotlib.pyplot as plt
+
+# Load the data
+ds = xr.tutorial.load_dataset('air_temperature')
+air = ds.air.isel(time=0)
+
+f, ((ax1, ax2), (ax3, ax4))  = plt.subplots(2, 2, figsize=(8, 6))
+
+# The first plot (in kelvins) chooses "viridis" and uses the data's min/max
+air.plot(ax=ax1, cbar_kwargs={'label':'K'})
+ax1.set_title('Kelvins: default')
+ax2.set_xlabel('')
+
+# The second plot (in celsius) now chooses "BuRd" and centers min/max around 0
+airc = air - 273.15
+airc.plot(ax=ax2, cbar_kwargs={'label':'°C'})
+ax2.set_title('Celsius: default')
+ax2.set_xlabel('')
+ax2.set_ylabel('')
+
+# The center doesn't have to be 0
+air.plot(ax=ax3, center=273.15, cbar_kwargs={'label':'K'})
+ax3.set_title('Kelvins: center=273.15')
+
+# Or it can be ignored
+airc.plot(ax=ax4, center=False, cbar_kwargs={'label':'°C'})
+ax4.set_title('Celsius: center=False')
+ax4.set_ylabel('')
+
+# Mke it nice
+plt.tight_layout()
+plt.show()

Diff for: doc/whats-new.rst

@@ -52,6 +52,14 @@ By `Keisuke Fujii <https://github.com/fujiisoup>`_.
   successful download (:issue:`1392`). By `Matthew Gidden
   <https://github.com/gidden>`_.
 
+Documentation
+~~~~~~~~~~~~~
+
+- A new `gallery <http://xarray.pydata.org/en/latest/auto_gallery/index.html>`_
+  allows to add interactive examples to the documentation.
+  By `Fabien Maussion <https://github.com/fmaussion>`_.
+  
+
 .. _whats-new.0.9.5:
 
 v0.9.5 (17 April, 2017)