API reference documentation

[wx4stg]

This branch adds documentation for functions and classes provided by pyxlma.
Documentation strings are compliant with the numpy format as I find this the most readable and informative (the other options being google or sphinx).

Documentation pages are built using mkdocs, specifically the mkdocstrings plugin and rendered in the mkdocs-material theme. I didn't want "yet another readthedocs page" and MyST Markdown does not yet have support for auto-generating API docs.

I eventually want to add support for examples using MyST/Executable Books. Since pyxlma is a pure python package, and all of its dependents are either pure python or have a WASM compatible pyodide wheel, it should be possible to run pyxlma in the browser using pyodide or jupyterlite. I am not yet sure whether I'll add this in this PR or if I'll make a separate one.

The goals of this PR are to:

1. Make pyxlma more accessible for new users
2. Allow for clear versioning with tested and documented releases
3. Allow for those releases to be published via conda-forge or similar distribution.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 48.00000% with 13 lines in your changes missing coverage. Please review.

Project coverage is 73.13%. Comparing base (97f8aaa) to head (1091a6d).

Files with missing lines	Patch %	Lines
pyxlma/coords.py	66.66%	4 Missing ⚠️
pyxlma/xarray_util.py	0.00%	4 Missing ⚠️
pyxlma/lmalib/io/lmatools.py	0.00%	3 Missing ⚠️
pyxlma/lmalib/flash/properties.py	66.66%	1 Missing ⚠️
pyxlma/lmalib/io/glm.py	0.00%	1 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #56      +/-   ##
==========================================
- Coverage   73.20%   73.13%   -0.08%     
==========================================
  Files          16       16              
  Lines        2086     2088       +2     
==========================================
  Hits         1527     1527              
- Misses        559      561       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[wx4stg]

it's a little worrying that github allows me to even attempt a deployment on someone else's GH pages... whenever this is ready for showtime I imagine there will be some fiddling with github settings to get this to publish.

still TODO for this pr (ranked from easiest to most difficult):

• An up to date README (reflecting the current state of the library) is desired
• Maybe a basic contributors' guide that at least explains the test system and how to document future code
• inline examples, brief snippets showing how to use each function
• notebook examples with higher-level workflows (maybe cross pollenate with some of the ideas in lmaworkshop)
  • MyST/ExecutableBooks seem to be currently designed for "I want to host a standalone webpage". There's a plugin for mkdocs that seems to do what I want: https://derthorsten.github.io/mkdocs-jupyterlite/notebook/
  • Getting datasets into the jupyterlite environment doesn't seem to be the easiest thing (thanks, CORS)
• Automated testing of the inline and notebook examples
• mkdocs has an option for show_source which embeds the entire source code of the function on the page. I want a link to github. There's a plugin for this but it's deprecated

There is a fair amount of things to consider before pyxlma is "a real python library":

• someone should proofread the docs
• I have written down a number of "inconsistencies" in the syntax that just feel clunky
• figuring out a versioning system
• setting up build/publishing with something like grayskull

[deeplycloudy]

Propose we use the example I've started in lmaworkshop to do the "notebook examples with higher-level workflows" - the WTLMA and GLM data are generally available, and it would be good to have a standalone example in this repository that serves as a general starting point for others. Love the JupyterLite idea, too.