Updates the documentation of the Dataset class to have clearer examples.

These changes to the documentation bring it into alignment with the
changes to the `Dataset` doc-string committed previously.

See issue pydata#8970 for more information.

doc/user-guide/data-structures.rst

@@ -282,27 +282,39 @@ variables (``data_vars``), coordinates (``coords``) and attributes (``attrs``).
 
 - ``attrs`` should be a dictionary.
 
-Let's create some fake data for the example we show above:
-
-.. ipython:: python
-
-    temp = 15 + 8 * np.random.randn(2, 2, 3)
-    precip = 10 * np.random.rand(2, 2, 3)
-    lon = [[-99.83, -99.32], [-99.79, -99.23]]
-    lat = [[42.25, 42.21], [42.63, 42.59]]
+Let's create some fake data for the example we show above. In this
+example dataset, we will represent measurements of the temperature and
+pressure that were made under various conditions:
+* the measurements were made on four different days;
+* they were made at two separate locations, which we will represent using
+  their latitude and longitude; and
+* they were made using three different sets of instruments, which we will
+  refer to as `'inst1'`, `'inst2'`, and `'inst3'`.
+
+.. ipython:: python
+
+    np.random.seed(0)
+    temperature = 15 + 8 * np.random.randn(2, 3, 4)
+    precipitation = 10 * np.random.rand(2, 3, 4)
+    lon = [-99.83, -99.32]
+    lat = [42.25, 42.21]
+    instruments = ['inst1', 'inst2', 'inst3']
+    time = pd.date_range("2014-09-06", periods=4)
+    reference_time = pd.Timestamp("2014-09-05")
 
     # for real use cases, its good practice to supply array attributes such as
     # units, but we won't bother here for the sake of brevity
     ds = xr.Dataset(
         {
-            "temperature": (["x", "y", "time"], temp),
-            "precipitation": (["x", "y", "time"], precip),
+            "temperature": (["loc", "instrument", "time"], temperature),
+            "precipitation": (["loc", "instrument", "time"], precipitation),
         },
         coords={
-            "lon": (["x", "y"], lon),
-            "lat": (["x", "y"], lat),
-            "time": pd.date_range("2014-09-06", periods=3),
-            "reference_time": pd.Timestamp("2014-09-05"),
+            "lon": (["loc"], lon),
+            "lat": (["loc"], lat),
+            "instrument": instruments,
+            "time": time,
+            "reference_time": reference_time,
         },
     )
     ds
@@ -387,12 +399,12 @@ example, to create this example dataset from scratch, we could have written:
 .. ipython:: python
 
     ds = xr.Dataset()
-    ds["temperature"] = (("x", "y", "time"), temp)
-    ds["temperature_double"] = (("x", "y", "time"), temp * 2)
-    ds["precipitation"] = (("x", "y", "time"), precip)
-    ds.coords["lat"] = (("x", "y"), lat)
-    ds.coords["lon"] = (("x", "y"), lon)
-    ds.coords["time"] = pd.date_range("2014-09-06", periods=3)
+    ds["temperature"] = (("loc", "instrument", "time"), temp)
+    ds["temperature_double"] = (("loc", "instrument", "time"), temp * 2)
+    ds["precipitation"] = (("loc", "instrument", "time"), precip)
+    ds.coords["lat"] = (("loc",), lat)
+    ds.coords["lon"] = (("loc",), lon)
+    ds.coords["time"] = pd.date_range("2014-09-06", periods=4)
     ds.coords["reference_time"] = pd.Timestamp("2014-09-05")
 
 To change the variables in a ``Dataset``, you can use all the standard dictionary
@@ -452,8 +464,8 @@ follow nested function calls:
 
     # these lines are equivalent, but with pipe we can make the logic flow
     # entirely from left to right
-    plt.plot((2 * ds.temperature.sel(x=0)).mean("y"))
-    (ds.temperature.sel(x=0).pipe(lambda x: 2 * x).mean("y").pipe(plt.plot))
+    plt.plot((2 * ds.temperature.sel(loc=0)).mean("instrument"))
+    (ds.temperature.sel(loc=0).pipe(lambda x: 2 * x).mean("instrument").pipe(plt.plot))
 
 Both ``pipe`` and ``assign`` replicate the pandas methods of the same names
 (:py:meth:`DataFrame.pipe <pandas.DataFrame.pipe>` and
@@ -479,7 +491,7 @@ dimension and non-dimension variables:
 
 .. ipython:: python
 
-    ds.coords["day"] = ("time", [6, 7, 8])
+    ds.coords["day"] = ("time", [6, 7, 8, 9])
     ds.swap_dims({"time": "day"})
 
 .. _coordinates: