Add Coordinates.from_xindex method (+ refactor API doc)

[benbovy]

This PR adds a new Coordinates.from_xindex() method as convenience for creating a new Coordinates object directly from an existing xarray.Index object. This will be useful, e.g., for #9543.

I picked the name from_xindex() as it is consistent with other API like Dataset.set_xindex() and Dataset.xindexes.

I also refactored the API reference documentation so Coordinates has its own expanded section with subsections similar to the ones of the Dataset, DataArray and DataTree sections. The Coordinates class likely won't be used as much as the other ones, but since it has some utility and it is public API I thought it'd be worth better expose it.

• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

[benbovy]

Ticket number #10000, nice! 🎉

[TomNicholas]

Seems a little inconsistent that the signature of this method only accepts one index, when the __init__ accepts multiple?

I'm also a bit unclear why you need to pass a Mapping from str names to indexes to __init__ but this method apparently doesn't require names?

[benbovy]

Ah yes I agree it is confusing and I'll clarify this.

__init__ is the low-level(-ish) constructor where we can pass any arbitrary mapping of coordinate variables (and optionally a mapping of Xarray indexes) that are just passed to a direct constructor with only little safety checks, whereas from_xindex creates a new Coordinates object from exactly one Xarray index via creating the variables and indexes mappings from the index object.

For example with a custom coordinate transform index (#9543):

class CustomIndex(CoordinateTransformIndex):
    ...

index = CustomIndex(...)

writing

coords = Coordinates.from_xindex(index)

is equivalent but safer and more convenient than writing

vars = index.create_variables()
indexes = {name: index for name in vars}
coords = Coordinates(coords=vars, indexes=indexes)

Alternatively to Coordinates.from_xindex() we could provide more specific constructors like Coordinates.from_transform() (alongside the already existing Coordinates.from_pandas_multiindex()), but Coordinates.from_xindex() is more generic and future-proof, i.e., it will just work with any custom index that can be created from anything other than pre-existing Xarray coordinates.

[TomNicholas]

Okay thank you for the explanation!