issue_comments: 1246487152

Thanks @dcherian and @TomNicholas for your feeback!

@dcherian I will reply to your inline comments when I'll integrate your suggestions in this PR.

@TomNicholas I answer to your comments below.

Bear in mind I don't think I've ever contributed a PR to xarray that touched indexes.py or indexing.py

That's exactly why your feedback is valuable!

When is my CustomIndex object consulted? Is it potentially for all basic operations (concat, join, align, indexing, etc?)

I agree this could be detailed more in the Index API docstrings in a consistent way. For some methods like equals, join and reindex_like it could be called in a lot of places, basically everything that relies on object alignment.

Why does there not need to be an index (in .indexes) if I do indexing with e.g. .isel but have no coordinates?

We should clarify that the aim of Index objects is to make more efficient all the operations made in the (discrete or continuous) space defined by the coordinate labels. That space is distinct from the discrete space defined by array element locations. All operations made in the latter space don't require any index.

Some Index API like Index.isel suggest otherwise, but those methods are rather for convenience, i.e., avoid users having to rebuild an index from scratch when it could be easily built from the existing one.

How is an xarray.PandasIndex different from a pd.Index?

I've tried to explain it in the "Index base class" section and the sections below, but maybe it should be emphasized more?

When I load the "air" tutorial data and it shows a Float64Index and DateTime64Index, where did they come from?

I guess you mean it is shown through ds.indexes?

ds.xindexes (vs. ds.indexes) still needs to be added in the docs (in a later PR?), which hopefully will address your concern here.

Finally it's not great that to explain Index objects we have to assume the user knows what xarray.Variable is, but Variable is still not really public API, and certainly isn't documented as comprehensively as DataArray and Dataset are.

I agree, although Variable is already documented in the "Xarray internals" section. Maybe Index also deserves its own entry there, where we could explain what indexes are, how they are different from variables (coordinates), how they are used or accessed in Xarray, etc.

Overall, I think that the whole "Xarray Internals" section could be streamlined beyond a bunch of loosely-coupled document pages.

I also think we need multiple simple examples.

I agree that we need more examples, but I also think that too much examples may tend to make things more confused.

One thing that I like very much in https://fastapi.tiangolo.com/ is how a small example is picked for each tutorial and then is shown by highlighting the relevant code for every subsection. Is it possible to do that with Sphinx / RST?

It's hard to show all features through one succinct example, though. Like @dcherian says in https://github.com/pydata/xarray/pull/6975#discussion_r967495773, we could invite people to look into the PandasIndex and PandasMultiIndex code for more details. My hope is that there will be more real examples (multi-coordinate, multi-dimensions) available in the future.