DAS-2155 - Merge datatree documentation into main docs.

[owenlittlejohns]

This PR migrates documentation for datatree from xarray/datatree_/docs into the main doc directory.

It seems a little iffy that a bunch of the references to the DataTree class, associated methods and other migrated functions all need to point to lower level locations (such as xarray.core.datatree.DataTree. When DataTree and friends are added to the public xarray API these references can be significantly simplified. This makes me wonder if we should couple the documentation change with that ability to access these classes from the main public API? (And if so, whether this PR is the time to do it?)

• Completes documentation migration step of Track merging datatree into xarray #8572
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

[keewis]

I would be fine with adding DataTree and open_datatree to the top-level module in this PR: adding documentation for DataTree to me means that we're publicly exposing it.

The only alternative I can think of would be to do this in a separate PR and merge that, then sync this PR with main.

[TomNicholas]

I agree with @keewis

The only alternative I can think of would be to do this in a separate PR and merge that, then sync this PR with main.

This might a little neater, but the result is the same either way.

[owenlittlejohns]

@TomNicholas - So the alternative here is exposing things in the public API, then updating this PR to have the correct references and merging this afterwards? (Just checking I read your last comment correctly)

Maybe I'm being a bit keen, but I'm tempted to keep both pieces (adding to the main API and including DataTree in the documentation) in the same PR to keep the documentation and public API in-sync.

[owenlittlejohns]

I have added open_datatree, DataTree, register_datatree_accessor, map_over_subtree and assert_isomorphic to the public API. The DataTree public API has some other exceptions in it (TreeIsomorphismError, InvalidTreeError and NotFoundInTreeError), but I was going by the things listed in #8572.

[flamingbear]

There are lots of little bitty things, but this looks great and the docs read well.

[owenlittlejohns]

@flamingbear - I've updated in most places you've suggested. Thanks for going through this so rigorously!

[TomNicholas]

(TreeIsomorphismError, InvalidTreeError and NotFoundInTreeError)

These should probably be added to the api.rst page after MergeError.

[owenlittlejohns]

@TomNicholas - to clarify your previous comment about those exceptions: would you like those 3 exceptions added to the public xarray API (TreeIsomorphismError, InvalidTreeError, NotFoundInTreeError)? Or would you just want them added to api.rst with their full current paths (pointing to e.g., xarray.core.treenode.InvalidTreeError).

I can definitely add them to the public API, but hadn't as those exceptions were not listed in #8572.

[TomNicholas]

@owenlittlejohns however it's already done for xarray's MergeError (which I happen to remember is listed in the public api.rst page). How exactly we do this isn't particularly important (hence why I forgot to include it in #8572), we just want to be consistent with other error types that we already have exposed publicly.

[owenlittlejohns]

Thanks for the guidance. I just added those three exceptions to the public API, so they are now consistent with MergeError.

[flamingbear]

I approved the changes here, but I don't know how to mark this as waiting for an event. (numpy 2)

[TomNicholas]

This is mergable, but unfortunately contingent on the outcome of #9077. Perhaps we should think about exactly how much of the docs wording would need to be changed if #9077 were accepted...

[flamingbear]

We should alter some of these examples slightly when a solution to #9475 is merged, and I have a few small comments, but I would like to merge this now and then fix those docs along with the code fixes, as long as @shoyer is okay with it!

To be crystal clear. We can merge this and update the docs with small tweaks when #9475 is updated?

Also to add the open_goups and other additions?

I'm 100% for this but only if others are ok with that.

[shoyer]

This looks great! Well done @flamingbear

I left a handful of mostly minor suggestions. I'm totally fine leaving some of these for follow-up work if you feel ready to merge this now.

[shoyer]

This may also be a good place to mention xarray's non-support for coordinates that conflict between parent and child nodes, and pointing users to open_groups as the recommended way to open such datasets.

[flamingbear]

I'm not sure this is the right place for that. This is under modifying existing zarr stores. They will always be aligned based on their data model? and this warning makes it sound like you're already changing the data groups?

[TomNicholas]

I think the point here is that somewhere in the IO docs for netCDF and Zarr there should be info or links to info about how open_datatree is not guaranteed to roundtrip but open_groups is.

[flamingbear]

Last comments to address are being added here so when I merge this we can find them easily:

• Where to mention open_groups DAS-2155 - Merge datatree documentation into main docs. #9033 (comment)
• example model dataset for Example datatree for use in tutorial documentation #9437? DAS-2155 - Merge datatree documentation into main docs. #9033 (comment)
• need open_groups example DAS-2155 - Merge datatree documentation into main docs. #9033 (comment)
• Need example for aligned and unaligned data set DAS-2155 - Merge datatree documentation into main docs. #9033 (comment)

This is ready but for these. Let's do them off of main and merge this.

[TomNicholas]

Amazing work @flamingbear ! Hopefully we can now return to a saner branch structure for the final push!