Update docs

Author: jsignell

doc/whats-new.rst

@@ -14,13 +14,10 @@ v2026.05.0 (unreleased)
 New Features
 ~~~~~~~~~~~~
 
-- Adds a new option ``chunks="preserve"`` when opening a dataset. This option
-  guarantees that chunks in xarray match on-disk chunks or multiples of them.
-  No chunk splitting allowed. (:pull:`11060`).
+- Change behavior of ``chunks="auto"`` to guarantee that chunks in xarray
+  match on-disk chunks or multiples of them. No automatic chunk splitting allowed.
+  (:pull:`11060`).
   By `Julia Signell <https://github.com/jsignell>`_
-- Added ``inherit='all_coords'`` option to :py:meth:`DataTree.to_dataset` to inherit
-  all parent coordinates, not just indexed ones (:issue:`10812`, :pull:`11230`).
-  By `Alfonso Ladino <https://github.com/aladinor>`_.
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~

xarray/backends/api.py

@@ -430,14 +430,12 @@ def open_dataset(
         "netcdf4" over "h5netcdf" over "scipy" (customizable via
         ``netcdf_engine_order`` in ``xarray.set_options()``). A custom backend
         class (a subclass of ``BackendEntrypoint``) can also be used.
-    chunks : int, dict, 'auto', 'dask-auto' or None, default: None
+    chunks : int, dict, 'auto', or None, default: None
         If provided, used to load the data into dask arrays.
 
         - ``chunks="auto"`` will use a chunking scheme that never splits encoded
           chunks. If encoded chunks are small then "auto" takes multiples of them
           over the largest dimension.
-        - ``chunks="dask-auto"`` will use dask ``auto`` chunking taking into account the
-          engine preferred chunks.
         - ``chunks=None`` skips using dask. This uses xarray's internally private
           :ref:`lazy indexing classes <internal design.lazy indexing>`,
           but data is eagerly loaded into memory as numpy arrays when accessed.
@@ -677,14 +675,12 @@ def open_dataarray(
         "netcdf4" over "h5netcdf" over "scipy" (customizable via
         ``netcdf_engine_order`` in ``xarray.set_options()``). A custom backend
         class (a subclass of ``BackendEntrypoint``) can also be used.
-    chunks : int, dict, 'auto', 'dask-auto', or None, default: None
+    chunks : int, dict, 'auto', or None, default: None
         If provided, used to load the data into dask arrays.
 
         - ``chunks="auto"`` will use a chunking scheme that never splits encoded
           chunks. If encoded chunks are small then "auto" takes multiples of them
           over the largest dimension.
-        - ``chunks='dask-auto'`` will use dask ``auto`` chunking taking into account the
-          engine preferred chunks.
         - ``chunks=None`` skips using dask. This uses xarray's internally private
           :ref:`lazy indexing classes <internal design.lazy indexing>`,
           but data is eagerly loaded into memory as numpy arrays when accessed.
@@ -906,11 +902,9 @@ def open_datatree(
         "h5netcdf" over "netcdf4" (customizable via ``netcdf_engine_order`` in
         ``xarray.set_options()``). A custom backend class (a subclass of
         ``BackendEntrypoint``) can also be used.
-    chunks : int, dict, 'auto', 'dask-auto', or None, default: None
+    chunks : int, dict, 'auto', or None, default: None
         If provided, used to load the data into dask arrays.
 
-        - ``chunks="dask-auto"`` will use dask ``auto`` chunking taking into account the
-          engine preferred chunks.
         - ``chunks="auto"`` will use a chunking scheme that never splits encoded
           chunks. If encoded chunks are small then "auto" takes multiples of them
           over the largest dimension.
@@ -1155,14 +1149,12 @@ def open_groups(
         ``xarray.set_options()``). A custom backend class (a subclass of
         ``BackendEntrypoint``) can also be used.
         can also be used.
-    chunks : int, dict, 'auto', 'dask-auto', or None, default: None
+    chunks : int, dict, 'auto', or None, default: None
         If provided, used to load the data into dask arrays.
 
         - ``chunks="auto"`` will use a chunking scheme that never splits encoded
           chunks. If encoded chunks are small then "auto" takes multiples of them
           over the largest dimension.
-        - ``chunks="dask-auto"`` will use dask ``auto`` chunking taking into account the
-          engine preferred chunks.
         - ``chunks=None`` skips using dask. This uses xarray's internally private
           :ref:`lazy indexing classes <internal design.lazy indexing>`,
           but data is eagerly loaded into memory as numpy arrays when accessed.
@@ -1430,7 +1422,7 @@ def open_mfdataset(
         concatenation along more than one dimension is desired, then ``paths`` must be a
         nested list-of-lists (see ``combine_nested`` for details). (A string glob will
         be expanded to a 1-dimensional list.)
-    chunks : int, dict, 'auto', 'dask-auto', or None, optional
+    chunks : int, dict, 'auto', or None, optional
         Dictionary with keys given by dimension names and values given by chunk sizes.
         In general, these should divide the dimensions of each dataset. If int, chunk
         each dimension by ``chunks``. By default, chunks will be chosen to match the

xarray/backends/zarr.py

@@ -1499,15 +1499,13 @@ def open_zarr(
         Array synchronizer provided to zarr
     group : str, optional
         Group path. (a.k.a. `path` in zarr terminology.)
-    chunks : int, dict, "auto", "dask-auto", or None, optional
+    chunks : int, dict, "auto", or None, optional
         Used to load the data into dask arrays. Default behavior is to use
         ``chunks={}`` if dask is available, otherwise ``chunks=None``.
 
         - ``chunks="auto"`` will use a chunking scheme that never splits encoded
           chunks. If encoded chunks are small then "auto" takes multiples of them
           over the largest dimension.
-        - ``chunks='dask-auto'`` will use dask ``auto`` chunking taking into account the
-          engine preferred chunks.
         - ``chunks=None`` skips using dask. This uses xarray's internally private
           :ref:`lazy indexing classes <internal design.lazy indexing>`,
           but data is eagerly loaded into memory as numpy arrays when accessed.

xarray/namedarray/parallelcompat.py

@@ -797,18 +797,18 @@ def preserve_chunks(
         """Quickly determine optimal chunks close to target size but never splitting
         previous_chunks.
 
-        This takes in a chunks argument potentially containing ``"preserve"`` for several
-        dimensions. This function replaces ``"preserve"`` with concrete dimension sizes that
+        This takes in a chunks argument potentially containing ``"auto"`` for several
+        dimensions. This function replaces ``"auto"`` with concrete dimension sizes that
         try to get chunks to be close to certain size in bytes, provided by the ``target=``
-        keyword. Any dimensions marked as ``"preserve"`` will potentially be multiplied
+        keyword. Any dimensions marked as ``"auto"`` will potentially be multiplied
         by some factor to get close to the byte target, while never splitting
         ``previous_chunks``. If chunks are non-uniform along a particular dimension
         then that dimension will always use exactly ``previous_chunks``.
 
         Examples
         --------
         >>> ChunkManagerEntrypoint.preserve_chunks(
-        ...     chunks=("preserve", "preserve", "preserve"),
+        ...     chunks=("auto", "auto", "auto"),
         ...     shape=(1280, 1280, 20),
         ...     target=500 * 1024,
         ...     typesize=8,
@@ -817,7 +817,7 @@ def preserve_chunks(
         (128, 128, 2)
 
         >>> ChunkManagerEntrypoint.preserve_chunks(
-        ...     chunks=("preserve", "preserve", 1),
+        ...     chunks=("auto", "auto", 1),
         ...     shape=(1280, 1280, 20),
         ...     target=1 * 1024 * 1024,
         ...     typesize=8,
@@ -826,7 +826,7 @@ def preserve_chunks(
         (128, 1024, 1)
 
         >>> ChunkManagerEntrypoint.preserve_chunks(
-        ...     chunks=("preserve", "preserve", 1),
+        ...     chunks=("auto", "auto", 1),
         ...     shape=(1280, 1280, 20),
         ...     target=1 * 1024 * 1024,
         ...     typesize=8,
@@ -838,7 +838,7 @@ def preserve_chunks(
         ----------
         chunks: tuple[int | str | tuple[int], ...]
             A tuple of either dimensions or tuples of explicit chunk dimensions
-            Some entries should be "preserve".
+            Some entries should be "auto".
         shape: tuple[int]
             The shape of the array
         target: int