Skip to content

Commit b0064b2

Browse files
keewisdcherian
keewis
authored and
dcherian
committed
Switch examples to notebooks + scipy19 docs improvements (#3557)
* Switch doc examples to use nbsphinx (#3105) * switching out examples to use nbsphinx * added jupyter_client to doc env * added ipykernel to doc env * Replace sphinx_gallery with notebook (#3106) * switching out examples to use nbsphinx * added jupyter_client to doc env * moved gallery to notebook * Allow other tutorial filename extensions (#3121) * switching out examples to use nbsphinx * added jupyter_client to doc env * allow non netcdf tutorial files * Added ROMS ocean model example notebook (#3116) * change name of test env to xarray-tests (#3110) * ROMS_ocean_model example added * Allow other tutorial filename extensions (#3121) * switching out examples to use nbsphinx * added jupyter_client to doc env * allow non netcdf tutorial files * Changed load to xr.tutorial.open_dataset(), and added some extra documentation. * change name of test env to xarray-tests (#3110) * ROMS_ocean_model example added * Changed load to xr.tutorial.open_dataset(), and added some extra documentation. * fixed colormap issues leftover from cmocean import * Added intro paragraph to ROMS example notebook, removed comments, and added citation in whats-new. * Add an example of ERA5 and GRIB data & visualization to the gallery (#3199) * Adds an example of ERA5 and GRIB data to the gallery * Add markdown narrative cells to GRIB example * Update load method to use xr.tutorial * Fix load method * require nbsphinx for the documentation builds * add more nbsphinx dependencies * install cfgrib using pip * add the eccodes library to the dependencies * remove the dependency on sphinx-gallery * add the ERA5 GRIB example to the list * update the documentation links Missing: section links in visualization_gallery.ipynb don't work yet, also the one in io.rst (it has a unicode char). * Fix leap year condition in monthly means example (#3464) * Typo correction in docs (#3387) * Update terminology.rst (#3455) Fixed broken link * Error in leap year? I've tried this script; however, it adds +1 to all months of the leap years. It sounds like an error, or I am wrong? So I wrote the condition "and month == 2" line 86 so that only the month of February gets +1. * Fix leap year (#3464) * Update doc/whats-new.rst Co-Authored-By: Deepak Cherian <[email protected]> * fix the reference to the rasterio geocoordinates docs * update whats-new.rst
1 parent 9717681 commit b0064b2

17 files changed

+1257
-1187
lines changed

‎ci/requirements/doc.yml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,23 @@ dependencies:
66
- python=3.7
77
- bottleneck
88
- cartopy
9+
- eccodes
910
- h5netcdf
11+
- ipykernel
1012
- ipython
1113
- iris
14+
- jupyter_client
15+
- nbsphinx
1216
- netcdf4
1317
- numpy
1418
- numpydoc
1519
- pandas<0.25 # Hack around https://github.com/pydata/xarray/issues/3369
1620
- rasterio
1721
- seaborn
1822
- sphinx
19-
- sphinx-gallery
2023
- sphinx_rtd_theme
2124
- zarr
25+
- pip
26+
- pip:
27+
- cfgrib
28+

‎doc/conf.py

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -76,20 +76,24 @@
7676
"numpydoc",
7777
"IPython.sphinxext.ipython_directive",
7878
"IPython.sphinxext.ipython_console_highlighting",
79-
"sphinx_gallery.gen_gallery",
79+
"nbsphinx",
8080
]
8181

8282
extlinks = {
8383
"issue": ("https://github.com/pydata/xarray/issues/%s", "GH"),
8484
"pull": ("https://github.com/pydata/xarray/pull/%s", "PR"),
8585
}
8686

87-
sphinx_gallery_conf = {
88-
"examples_dirs": "gallery",
89-
"gallery_dirs": "auto_gallery",
90-
"backreferences_dir": False,
91-
"expected_failing_examples": list(allowed_failures),
92-
}
87+
nbsphinx_timeout = 600
88+
nbsphinx_execute = "always"
89+
nbsphinx_prolog = """
90+
{% set docname = env.doc2path(env.docname, base=None) %}
91+
92+
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 }}>`_.
93+
94+
.. |Binder| image:: https://mybinder.org/badge.svg
95+
:target: https://mybinder.org/v2/gh/pydata/xarray/master?urlpath=lab/tree/doc/{{ docname }}
96+
"""
9397

9498
autosummary_generate = True
9599
autodoc_typehints = "none"
@@ -137,7 +141,7 @@
137141

138142
# List of patterns, relative to source directory, that match files and
139143
# directories to ignore when looking for source files.
140-
exclude_patterns = ["_build"]
144+
exclude_patterns = ["_build", "**.ipynb_checkpoints"]
141145

142146
# The reST default role (used for this markup: `text`) to use for all
143147
# documents.

‎doc/data-structures.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -485,14 +485,14 @@ in xarray:
485485
:py:class:`pandas.Index` internally to store their values.
486486

487487
- **non-dimension coordinates** are variables that contain coordinate
488-
data, but are not a dimension coordinate. They can be multidimensional
489-
(see :ref:`examples.multidim`), and there is no relationship between the
490-
name of a non-dimension coordinate and the name(s) of its dimension(s).
491-
Non-dimension coordinates can be useful for indexing or plotting; otherwise,
492-
xarray does not make any direct use of the values associated with them.
493-
They are not used for alignment or automatic indexing, nor are they required
494-
to match when doing arithmetic
495-
(see :ref:`coordinates math`).
488+
data, but are not a dimension coordinate. They can be multidimensional (see
489+
:ref:`/examples/multidimensional-coords.ipynb`), and there is no
490+
relationship between the name of a non-dimension coordinate and the
491+
name(s) of its dimension(s). Non-dimension coordinates can be
492+
useful for indexing or plotting; otherwise, xarray does not make any
493+
direct use of the values associated with them. They are not used
494+
for alignment or automatic indexing, nor are they required to match
495+
when doing arithmetic (see :ref:`coordinates math`).
496496

497497
.. note::
498498

‎doc/examples.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ Examples
77
examples/weather-data
88
examples/monthly-means
99
examples/multidimensional-coords
10-
auto_gallery/index
10+
examples/visualization_gallery
11+
examples/ROMS_ocean_model
12+
examples/ERA5-GRIB-example

‎doc/examples/ERA5-GRIB-example.ipynb

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# GRIB Data Example "
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"GRIB format is commonly used to disemminate atmospheric model data. With Xarray and the cfgrib engine, GRIB data can easily be analyzed and visualized."
15+
]
16+
},
17+
{
18+
"cell_type": "code",
19+
"execution_count": null,
20+
"metadata": {},
21+
"outputs": [],
22+
"source": [
23+
"import xarray as xr\n",
24+
"import matplotlib.pyplot as plt"
25+
]
26+
},
27+
{
28+
"cell_type": "markdown",
29+
"metadata": {},
30+
"source": [
31+
"To read GRIB data, you can use `xarray.load_dataset`. The only extra code you need is to specify the engine as `cfgrib`."
32+
]
33+
},
34+
{
35+
"cell_type": "code",
36+
"execution_count": null,
37+
"metadata": {},
38+
"outputs": [],
39+
"source": [
40+
"ds = xr.tutorial.load_dataset('era5-2mt-2019-03-uk.grib', engine='cfgrib')"
41+
]
42+
},
43+
{
44+
"cell_type": "markdown",
45+
"metadata": {},
46+
"source": [
47+
"Let's create a simple plot of 2-m air temperature in degrees Celsius:"
48+
]
49+
},
50+
{
51+
"cell_type": "code",
52+
"execution_count": null,
53+
"metadata": {},
54+
"outputs": [],
55+
"source": [
56+
"ds = ds - 273.15\n",
57+
"ds.t2m[0].plot(cmap=plt.cm.coolwarm)"
58+
]
59+
},
60+
{
61+
"cell_type": "markdown",
62+
"metadata": {},
63+
"source": [
64+
"With CartoPy, we can create a more detailed plot, using built-in shapefiles to help provide geographic context:"
65+
]
66+
},
67+
{
68+
"cell_type": "code",
69+
"execution_count": null,
70+
"metadata": {},
71+
"outputs": [],
72+
"source": [
73+
"import cartopy.crs as ccrs\n",
74+
"import cartopy\n",
75+
"fig = plt.figure(figsize=(10,10))\n",
76+
"ax = plt.axes(projection=ccrs.Robinson())\n",
77+
"ax.coastlines(resolution='10m')\n",
78+
"plot = ds.t2m[0].plot(cmap=plt.cm.coolwarm, transform=ccrs.PlateCarree(), cbar_kwargs={'shrink':0.6})\n",
79+
"plt.title('ERA5 - 2m temperature British Isles March 2019')"
80+
]
81+
},
82+
{
83+
"cell_type": "markdown",
84+
"metadata": {},
85+
"source": [
86+
"Finally, we can also pull out a time series for a given location easily:"
87+
]
88+
},
89+
{
90+
"cell_type": "code",
91+
"execution_count": null,
92+
"metadata": {},
93+
"outputs": [],
94+
"source": [
95+
"ds.t2m.sel(longitude=0,latitude=51.5).plot()\n",
96+
"plt.title('ERA5 - London 2m temperature March 2019')"
97+
]
98+
}
99+
],
100+
"metadata": {
101+
"kernelspec": {
102+
"display_name": "Python 3",
103+
"language": "python",
104+
"name": "python3"
105+
},
106+
"language_info": {
107+
"codemirror_mode": {
108+
"name": "ipython",
109+
"version": 3
110+
},
111+
"file_extension": ".py",
112+
"mimetype": "text/x-python",
113+
"name": "python",
114+
"nbconvert_exporter": "python",
115+
"pygments_lexer": "ipython3",
116+
"version": "3.7.3"
117+
}
118+
},
119+
"nbformat": 4,
120+
"nbformat_minor": 4
121+
}

0 commit comments

Comments
 (0)