Docstring and documentation improvement for the Dataset class

[noahbenson]

The example in the doc-string of the Dataset class prior to this commit uses an example array whose size is 2 x 2 x 3 with the first two dimensions labeled "x" and "y" and the final dimension labeled "time". This was confusing due to the fact that "x" and "y" are just arbitrary names for these axes and that no reason is given for the data to be organized in a 2x2x3 array instead of a 2x2 matrix. This commit clarifies the example.

Additionally, this PR contains updates to the documentation, specifically the user-guide/data-structures.rst file; the updates bring the documentation examples into alignment with the doc-string change. Unfortunately, I wasn't able to build the documentation, so this will need to be checked. (I followed the instructions here, but despite cfgrib working fine, I got an error about how it wasn't a valid engine.)

See issue #8970 for more information.

• Closes Example code in the documentation for Dataset is not clear #8970

[welcome]

Thank you for opening this pull request! It may take us a few days to respond here, so thank you for being patient.
If you have questions, some answers may be found in our contributing guidelines.

[max-sixty]

Thanks!

We do get an error in the doc build — TypeError: Variable 'temperature': Using a DataArray object to construct a variable is ambiguous, please extract the data using the .data property.. Check out https://readthedocs.org/projects/xray/builds/24178355/ for more. I also struggle to build the docs...

For the doctests, you may be on a slightly older version of xarray which doesn't print sizes, so worth updating. If you want to update the output automatically I have a project https://github.com/max-sixty/pytest-accept which does this automatically!

[noahbenson]

Thanks. That error does not make sense to me—I have not materially changed it from what currently exists in the docs here where the line is ds["temperature"] = (("x", "y", "time"), temp). In fact, I think the error should have been that temp is not a declared symbol? (I changed the temp in the example to temperature but did not change it in this line.) That said, I don't use this tool for documentation, so I'm probably missing something.

Anyway, assuming that the temp versus temperature is fundamentally the problem, my last push should have fixed those issues... 🤞

[max-sixty]

Great — if anyone has any thoughts, feel free to comment; otherwise let's merge.

Thanks @noahbenson , nice improvement to a core part of the docs...

[max-sixty]

Any other thoughts? There's some discussion in #8970. I think it's reasonable to merge tomorrow without other suggestions.

Give this a 👎 for disagreement (which is welcome ofc)

[welcome]

Congratulations on completing your first pull request! Welcome to Xarray! We are proud of you, and hope to see you again!

[max-sixty]

Thanks @noahbenson ! I think this was a v nice improvement, thanks for pushing through!