merge scipy19 docs

ci/requirements/doc.yml

@@ -6,16 +6,23 @@ dependencies:
   - python=3.7
   - bottleneck
   - cartopy
+  - eccodes
   - h5netcdf
+  - ipykernel
   - ipython
   - iris
+  - jupyter_client
+  - nbsphinx
   - netcdf4
   - numpy
   - numpydoc
   - pandas<0.25  # Hack around https://github.com/pydata/xarray/issues/3369
   - rasterio
   - seaborn
   - sphinx
-  - sphinx-gallery
   - sphinx_rtd_theme
   - zarr
+  - pip
+  - pip:
+    - cfgrib
+

doc/conf.py

@@ -76,20 +76,24 @@
     "numpydoc",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
-    "sphinx_gallery.gen_gallery",
+    "nbsphinx",
 ]
 
 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,
-    "expected_failing_examples": list(allowed_failures),
-}
+nbsphinx_timeout = 600
+nbsphinx_execute = "always"
+nbsphinx_prolog = """
+{% set docname = env.doc2path(env.docname, base=None) %}
+
+You can run this notebook in a `live session <https://mybinder.org/v2/gh/pydata/xarray/doc/examples/master?urlpath=lab/tree/doc/{{ docname }}>`_ |Binder| or view it `on Github <https://github.com/pydata/xarray/blob/master/doc/{{ docname }}>`_.
+
+.. |Binder| image:: https://mybinder.org/badge.svg
+   :target: https://mybinder.org/v2/gh/pydata/xarray/master?urlpath=lab/tree/doc/{{ docname }}
+"""
 
 autosummary_generate = True
 autodoc_typehints = "none"
@@ -137,7 +141,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

doc/data-structures.rst

@@ -485,14 +485,14 @@ in xarray:
   :py:class:`pandas.Index` internally to store their values.
 
 - **non-dimension coordinates** are variables that contain coordinate
-  data, but are not a dimension coordinate. They can  be multidimensional
-  (see :ref:`examples.multidim`), and there is no relationship between the
-  name of a non-dimension coordinate and the name(s) of its dimension(s).
-  Non-dimension coordinates can be useful for indexing or plotting; otherwise,
-  xarray does not make any direct use of the values associated with them.
-  They are not used for alignment or automatic indexing, nor are they required
-  to match when doing arithmetic
-  (see :ref:`coordinates math`).
+  data, but are not a dimension coordinate. They can be multidimensional (see
+  :ref:`/examples/multidimensional-coords.ipynb`), and there is no
+  relationship between the name of a non-dimension coordinate and the
+  name(s) of its dimension(s).  Non-dimension coordinates can be
+  useful for indexing or plotting; otherwise, xarray does not make any
+  direct use of the values associated with them.  They are not used
+  for alignment or automatic indexing, nor are they required to match
+  when doing arithmetic (see :ref:`coordinates math`).
 
 .. note::
 

doc/examples.rst

@@ -7,4 +7,6 @@ Examples
     examples/weather-data
     examples/monthly-means
     examples/multidimensional-coords
-    auto_gallery/index
+    examples/visualization_gallery
+    examples/ROMS_ocean_model
+    examples/ERA5-GRIB-example

doc/examples/ERA5-GRIB-example.ipynb

@@ -0,0 +1,121 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# GRIB Data Example "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "GRIB format is commonly used to disemminate atmospheric model data. With Xarray and the cfgrib engine, GRIB data can easily be analyzed and visualized."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import matplotlib.pyplot as plt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To read GRIB data, you can use `xarray.load_dataset`. The only extra code you need is to specify the engine as `cfgrib`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.tutorial.load_dataset('era5-2mt-2019-03-uk.grib', engine='cfgrib')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's create a simple plot of 2-m air temperature in degrees Celsius:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = ds - 273.15\n",
+    "ds.t2m[0].plot(cmap=plt.cm.coolwarm)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "With CartoPy, we can create a more detailed plot, using built-in shapefiles to help provide geographic context:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import cartopy.crs as ccrs\n",
+    "import cartopy\n",
+    "fig = plt.figure(figsize=(10,10))\n",
+    "ax = plt.axes(projection=ccrs.Robinson())\n",
+    "ax.coastlines(resolution='10m')\n",
+    "plot = ds.t2m[0].plot(cmap=plt.cm.coolwarm, transform=ccrs.PlateCarree(), cbar_kwargs={'shrink':0.6})\n",
+    "plt.title('ERA5 - 2m temperature British Isles March 2019')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, we can also pull out a time series for a given location easily:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds.t2m.sel(longitude=0,latitude=51.5).plot()\n",
+    "plt.title('ERA5 - London 2m temperature March 2019')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}