Doc Cleanup

[philipc2]

Closes #641 #884 #743 #407

Overview

• Refactored API reference to be better aligned with similar packages, such as xarray
• Corrected the order of sections in the User Guide toctree
• Updated the README
• Updated docstrings
• Fixed typos in some user guide sections

Rendered Documentation with Changes

[philipc2]

@erogluorhan @rajeeja

Thoughts on removing the "Internal" and "User" API split that we've been employing since the start of the package? The only benefit of having an internal API on our documentation would be for developers.

The majority of documentations I've looked at for packages only consist of the user API.

Xarray doesn't provide an internal API.

https://docs.xarray.dev/en/stable/api.html

[rajeeja]

Just yesterday I had a discussion with @rljacob

Yes, we should remove that distinction. There are a few changes I have in mind for cleaning up the Docs. I will also contribute to the pr.

[philipc2]

Just yesterday I had a discussion with @rljacob

Yes, we should remove that distinction. There are a few changes I have in mind for cleaning up the Docs. I will also contribute to the pr.

Sounds great! Feel free to discuss anything here. We could hop on a call and/or work on some together next week also.

[erogluorhan]

Sounds good to me

[philipc2]

@rajeeja @erogluorhan @aaronzedwick @rytam2

This should be ready for review now. There's a good chance I've probably missed something (especially in the API reference). I'm also open to any other improvements that either of you may suggest!

[rajeeja]

https://uxarray--977.org.readthedocs.build/en/977/internal_api/generated/uxarray.UxDataArray.html#uxarray.UxDataArray.__init__

only difference and gradient have links.

gradient examples isn't formatted right: https://uxarray--977.org.readthedocs.build/en/977/generated/uxarray.UxDataArray.gradient.html#uxarray.UxDataArray.gradient

[philipc2]

https://uxarray--977.org.readthedocs.build/en/977/internal_api/generated/uxarray.UxDataArray.html#uxarray.UxDataArray.__init__

only difference and gradient have links.

gradient examples isn't formatted right: https://uxarray--977.org.readthedocs.build/en/977/generated/uxarray.UxDataArray.gradient.html#uxarray.UxDataArray.gradient

Good catches!

[aaronzedwick]

A lot of functions (as you can see in the image) have (...[,...]) or simply [...]. What is it meant to symbolize? That it takes arguments? Looks a little strange to me.

[philipc2]

A lot of functions (as you can see in the image) have (...[,...]) or simply [...]. What is it meant to symbolize? That it takes arguments? Looks a little strange to me.

This is most likely due to a limitation of character length for how many parameters can be show.

[rytam2]

I am thinking a bit more on the Grid section, as this section may be accessed more by folks since UXarray is developed for unstructured grids:

• Perhaps changing the subheading like Constructor to Creating a Grid/UxDataArray/UxDataSet would be more intuitive?
• Also would making Coordinate Attributes as a single subheading, and have spherical coordinates and cartesian coordinates a sub-subheading be a good idea?
• Suggest moving Descriptors following right after Dimensions for more intuitive understanding in case people reading API from top-down, instead of being in between the coordinates section and connectivity.
• Suggest adding unit for Grid.edge_node_distances and Grid.edge_face_distances

Other sections looks very neat!

[philipc2]

Thanks for the comments @rytam2 !

Perhaps changing the subheading like Constructor to Creating a Grid/UxDataArray/UxDataSet would be more intuitive?

The constructor isn't intended for direct construction, as that is what the class methods and API functions are for.

• Also would making Coordinate Attributes as a single subheading, and have spherical coordinates and cartesian coordinates a sub-subheading be a good idea?

This might introduce too many sub-headers.

• Suggest moving Descriptors following right after Dimensions for more intuitive understanding in case people reading API from top-down, instead of being in between the coordinates section and connectivity.

Right now the order is:

• Dimensions
• Coordinates
• Connectivity
• Descriptors

Do you mean moving it before the coordinates?

• Suggest adding unit for Grid.edge_node_distances and Grid.edge_face_distances

Good idea! Will add this

[rytam2]

The constructor isn't intended for direct construction, as that is what the class methods and API functions are for.

Got it; just wondering is there another term for constructor? It's fine too if there isn't.

This might introduce too many sub-headers.

Fair, I think we can keep it as is.

Do you mean moving it before the coordinates?

Yes!