document restrictions to the inline repr

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

doc/internals.rst

@@ -10,6 +10,16 @@ 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 sparse
+    import xarray as xr
+
+    np.random.seed(123456)
+
 Variable objects
 ----------------
 
@@ -74,18 +84,23 @@ argument:
 
         ...
 
-
-Extending xarray
-----------------
+To avoid duplicated information, this method must omit information about the shape and
+:term:`dtype`. For example, the string representation of a ``dask`` array or a
+``sparse`` matrix would be:
 
 .. ipython:: python
-    :suppress:
 
-    import numpy as np
-    import pandas as pd
-    import xarray as xr
+    a = np.eye(10)
+    a[[5, 7, 3, 0], [6, 8, 2, 9]] = 2
+    a = sparse.COO.from_numpy(a)
+    a
 
-    np.random.seed(123456)
+    xr.Dataset(
+        {"a": ("x", np.linspace(0, 1, 10)), "b": (("y", "z"), sparse.COO.from_numpy(a))}
+    ).chunk({"x": 2})
+
+Extending xarray
+----------------
 
 xarray is designed as a general purpose library, and hence tries to avoid
 including overly domain specific functionality. But inevitably, the need for more