Update Custom Indexes section in api.rst (#10517)

Author: dcherian

doc/api-hidden.rst

@@ -515,22 +515,6 @@
    CFTimeIndex.values
    CFTimeIndex.year
 
-   Index.from_variables
-   Index.concat
-   Index.stack
-   Index.unstack
-   Index.create_variables
-   Index.should_add_coord_to_array
-   Index.to_pandas_index
-   Index.isel
-   Index.sel
-   Index.join
-   Index.reindex_like
-   Index.equals
-   Index.roll
-   Index.rename
-   Index.copy
-
    indexes.RangeIndex.start
    indexes.RangeIndex.stop
    indexes.RangeIndex.step

doc/api.rst

@@ -978,6 +978,40 @@ and DataTree objects, respectively.
    core.coordinates.DataArrayCoordinates
    core.coordinates.DataTreeCoordinates
 
+Indexes
+=======
+
+Default, pandas-backed indexes built-in to Xarray:
+
+.. autosummary::
+   :toctree: generated/
+
+   indexes.PandasIndex
+   indexes.PandasMultiIndex
+
+
+More complex indexes built-in to Xarray:
+
+.. autosummary::
+   :toctree: generated/
+
+   CFTimeIndex
+   indexes.RangeIndex
+   indexes.NDPointIndex
+
+
+Creating indexes
+----------------
+.. autosummary::
+   :toctree: generated/
+
+   cftime_range
+   date_range
+   date_range_like
+   indexes.RangeIndex.arange
+   indexes.RangeIndex.linspace
+
+
 Universal functions
 ===================
 
@@ -1571,31 +1605,39 @@ Custom Indexes
 ==============
 .. currentmodule:: xarray
 
+Building custom indexes
+-----------------------
+
+These classes are building blocks for more complex Indexes:
+
 .. autosummary::
    :toctree: generated/
 
-   CFTimeIndex
-   indexes.RangeIndex
+   indexes.CoordinateTransform
    indexes.CoordinateTransformIndex
    indexes.NDPointIndex
 
-Creating custom indexes
------------------------
-.. autosummary::
-   :toctree: generated/
-
-   cftime_range
-   date_range
-   date_range_like
-   indexes.RangeIndex.arange
-   indexes.RangeIndex.linspace
+The Index base class for building custom indexes:
 
-Building custom indexes
------------------------
 .. autosummary::
    :toctree: generated/
 
-   indexes.CoordinateTransform
+   Index.from_variables
+   Index.concat
+   Index.stack
+   Index.unstack
+   Index.create_variables
+   Index.should_add_coord_to_array
+   Index.to_pandas_index
+   Index.isel
+   Index.sel
+   Index.join
+   Index.reindex_like
+   Index.equals
+   Index.roll
+   Index.rename
+   Index.copy
+
 
 Tutorial
 ========
@@ -1702,14 +1744,6 @@ Advanced API
 ..    Missing:
 ..    ``DataTree.set_close``
 
-Default, pandas-backed indexes built-in Xarray:
-
-.. autosummary::
-   :toctree: generated/
-
-   indexes.PandasIndex
-   indexes.PandasMultiIndex
-
 These backends provide a low-level interface for lazily loading data from
 external file-formats or protocols, and can be manually invoked to create
 arguments for the ``load_store`` and ``dump_to_store`` Dataset methods:

xarray/core/coordinate_transform.py

@@ -9,8 +9,9 @@
 class CoordinateTransform:
     """Abstract coordinate transform with dimension & coordinate names.
 
-    EXPERIMENTAL (not ready for public use yet).
-
+    .. caution::
+        This API is experimental and subject to change. Please report any bugs or surprising
+        behaviour you encounter.
     """
 
     coord_names: tuple[Hashable, ...]

xarray/core/dataarray.py

@@ -6915,7 +6915,7 @@ def groupby(
         :ref:`groupby`
             Users guide explanation of how to group and bin data.
 
-        :doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns`
+        :doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns`
             Tutorial on :py:func:`~xarray.DataArray.Groupby` for windowed computation
 
         :doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray`

xarray/core/dataset.py

@@ -9955,7 +9955,7 @@ def groupby(
         :ref:`groupby`
             Users guide explanation of how to group and bin data.
 
-        :doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns`
+        :doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns`
             Tutorial on :py:func:`~xarray.Dataset.Groupby` for windowed computation.
 
         :doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray`

xarray/core/indexes.py

@@ -1455,14 +1455,15 @@ def rename(self, name_dict, dims_dict):
 class CoordinateTransformIndex(Index):
     """Helper class for creating Xarray indexes based on coordinate transforms.
 
-    EXPERIMENTAL (not ready for public use yet).
-
     - wraps a :py:class:`CoordinateTransform` instance
     - takes care of creating the index (lazy) coordinates
     - supports point-wise label-based selection
     - supports exact alignment only, by comparing indexes based on their transform
       (not on their explicit coordinate labels)
 
+    .. caution::
+        This API is experimental and subject to change. Please report any bugs or surprising
+        behaviour you encounter.
     """
 
     transform: CoordinateTransform