From f1bec6e1e1dbf2475daf55c5b92fcdd953db8ad4 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Tue, 16 Feb 2021 01:08:52 +0100
Subject: [PATCH 1/6] move the suppressed import block to the top

---
 doc/internals.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/internals.rst b/doc/internals.rst
index 60d32128c60..59e6e585ae0 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -10,6 +10,15 @@ stack, NumPy and pandas. It is written in pure Python (no C or Cython
 extensions), which makes it easy to develop and extend. Instead, we push
 compiled code to :ref:`optional dependencies<installing>`.
 
+.. ipython:: python
+    :suppress:
+
+    import numpy as np
+    import pandas as pd
+    import xarray as xr
+
+    np.random.seed(123456)
+
 Variable objects
 ----------------
 
@@ -78,15 +87,6 @@ argument:
 Extending xarray
 ----------------
 
-.. ipython:: python
-    :suppress:
-
-    import numpy as np
-    import pandas as pd
-    import xarray as xr
-
-    np.random.seed(123456)
-
 xarray is designed as a general purpose library, and hence tries to avoid
 including overly domain specific functionality. But inevitably, the need for more
 domain specific logic arises.

From 418808dfafd803c181c06053ce8ff9d855a71db0 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Tue, 16 Feb 2021 01:11:50 +0100
Subject: [PATCH 2/6] clarify that shape and dtype must not be included in the
 inline repr

---
 doc/internals.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/internals.rst b/doc/internals.rst
index 59e6e585ae0..13ffaad6e9f 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -83,6 +83,8 @@ argument:
 
         ...
 
+To avoid duplicated information, this method must omit information about the shape and
+:term:`dtype`.
 
 Extending xarray
 ----------------

From eeabc16d569591f7a241e8afcf3cca337699bbdb Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Tue, 16 Feb 2021 01:12:06 +0100
Subject: [PATCH 3/6] show dask and sparse arrays as examples for inline reprs
 [skip-ci]

---
 doc/internals.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/internals.rst b/doc/internals.rst
index 13ffaad6e9f..72b9e176a48 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -15,6 +15,7 @@ compiled code to :ref:`optional dependencies<installing>`.
 
     import numpy as np
     import pandas as pd
+    import sparse
     import xarray as xr
 
     np.random.seed(123456)
@@ -84,7 +85,19 @@ argument:
         ...
 
 To avoid duplicated information, this method must omit information about the shape and
-:term:`dtype`.
+:term:`dtype`. For example, the string representation of a ``dask`` array or a
+``sparse`` matrix would be:
+
+.. ipython:: python
+
+    a = np.eye(10)
+    a[[5, 7, 3, 0], [6, 8, 2, 9]] = 2
+    a = sparse.COO.from_numpy(a)
+    a
+
+    xr.Dataset(
+        {"a": ("x", np.linspace(0, 1, 10)), "b": (("y", "z"), sparse.COO.from_numpy(a))}
+    ).chunk({"x": 2})
 
 Extending xarray
 ----------------

From 07134804d1a4e7f7ab9cdd96093fce28c90ed965 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Wed, 17 Feb 2021 22:19:09 +0100
Subject: [PATCH 4/6] add sparse to the doc environment [skip-ci]

---
 ci/requirements/doc.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml
index e092272654b..cdb763e9748 100644
--- a/ci/requirements/doc.yml
+++ b/ci/requirements/doc.yml
@@ -23,6 +23,7 @@ dependencies:
   - rasterio>=1.1
   - seaborn
   - setuptools
+  - sparse
   - sphinx=3.3
   - sphinx_rtd_theme>=0.4
   - sphinx-autosummary-accessors

From e2e06bcfeca897d09c70afabd8f64ee38ee3f77b Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Wed, 17 Feb 2021 23:01:07 +0100
Subject: [PATCH 5/6] don't convert to sparse twice [skip-ci]

---
 doc/internals.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/internals.rst b/doc/internals.rst
index 72b9e176a48..bd7255342dc 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -95,9 +95,9 @@ To avoid duplicated information, this method must omit information about the sha
     a = sparse.COO.from_numpy(a)
     a
 
-    xr.Dataset(
-        {"a": ("x", np.linspace(0, 1, 10)), "b": (("y", "z"), sparse.COO.from_numpy(a))}
-    ).chunk({"x": 2})
+    xr.Dataset({"a": ("x", np.linspace(0, 1, 10)), "b": (("y", "z"), a)}).chunk(
+        {"x": 2}
+    )
 
 Extending xarray
 ----------------

From 5394d96ec251397505f622f4269e2b3b06a61de4 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Wed, 17 Feb 2021 23:24:36 +0100
Subject: [PATCH 6/6] correctly name the variables and manually create the dask
 array [skip-ci]

---
 doc/internals.rst | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/doc/internals.rst b/doc/internals.rst
index bd7255342dc..f3d67de9077 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -13,6 +13,7 @@ compiled code to :ref:`optional dependencies<installing>`.
 .. ipython:: python
     :suppress:
 
+    import dask.array as da
     import numpy as np
     import pandas as pd
     import sparse
@@ -90,14 +91,15 @@ To avoid duplicated information, this method must omit information about the sha
 
 .. ipython:: python
 
-    a = np.eye(10)
-    a[[5, 7, 3, 0], [6, 8, 2, 9]] = 2
-    a = sparse.COO.from_numpy(a)
+    a = da.linspace(0, 1, 20, chunks=2)
     a
 
-    xr.Dataset({"a": ("x", np.linspace(0, 1, 10)), "b": (("y", "z"), a)}).chunk(
-        {"x": 2}
-    )
+    b = np.eye(10)
+    b[[5, 7, 3, 0], [6, 8, 2, 9]] = 2
+    b = sparse.COO.from_numpy(b)
+    b
+
+    xr.Dataset({"a": ("x", a), "b": (("y", "z"), b)})
 
 Extending xarray
 ----------------