Update Custom Indexes section in api.rst

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

@@ -1571,12 +1571,22 @@ Custom Indexes
 ==============
 .. currentmodule:: xarray
 
+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.CoordinateTransformIndex
    indexes.NDPointIndex
 
 Creating custom indexes
@@ -1590,12 +1600,38 @@ Creating custom indexes
    indexes.RangeIndex.arange
    indexes.RangeIndex.linspace
 
+The Index base class for building custom indexes:
+
+.. autosummary::
+   :toctree: generated/
+
+   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
+
 Building custom indexes
 -----------------------
+
+These classes are building blocks for more complex Indexes:
+
 .. autosummary::
    :toctree: generated/
 
    indexes.CoordinateTransform
+   indexes.CoordinateTransformIndex
+   indexes.NDPointIndex
 
 Tutorial
 ========
@@ -1702,14 +1738,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/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