diff --git a/.gitignore b/.gitignore index 9ecf252..53c1cde 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/jupyter_execute # PyBuilder .pybuilder/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..279f97a --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: "2" + +build: + os: "ubuntu-20.04" + tools: + python: "3.10" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..641e200 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,62 @@ +import os +import sys + +sys.path.insert(0, os.path.abspath("../")) +sys.path.insert(0, os.path.abspath("../xarray_subset_grid")) +sys.path.insert(0, os.path.abspath("../examples")) + +project = "xarray_subset_grid" +copyright = "2024, IOOS" +author = "IOOS" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx_autodoc_typehints", + "sphinx.ext.viewcode", + "sphinx.ext.todo", + "sphinx.ext.autosummary", + "myst_nb", +] + +autodoc_default_options = { + "members": True, + "undoc-members": False, + "show-inheritance": True, +} +autosummary_generate = True +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "**.ipynb_checkpoints", + "jupyter_execute", +] +autodoc_mock_imports = ["numpy", "xarray"] + +language = "en" + +# -- Notebook Configuration --------------------------------------------------- +# https://myst-nb.readthedocs.io/en/latest/quickstart.html +source_suffix = { + ".rst": "restructuredtext", + ".ipynb": "myst-nb", + ".md": "myst-nb", +} +suppress_warnings = ["mystnb.unknown_mime_type", "mystnb"] +nb_execution_mode = "off" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] + +# -- Options for todo extension ---------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration + +todo_include_todos = True diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..6326ba4 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,173 @@ +.. _contributing: + +Contributors Guide +================== + +Interested in improving xarray-subset-grid? Have a few minutes to tackle +an issue? Or improve the documentation? + +Introduction +------------ + +First off, thank you for considering contributing to xarray-subset-grid. +Following these guidelines helps to communicate that you respect the +time of the developers managing and developing these open source +projects. In return, they should reciprocate that respect in addressing +your issue, assessing changes, and helping you finalize your pull +requests. So, please take a few minutes to read through this guide. + +What Can I Do? +-------------- + +- Tackle any issues you wish! +- Contribute code you already have. It does not need to be perfect! We + will help you clean things up, test it, etc. +- Make a tutorial or example of how to do something. +- Improve documentation of a feature you found troublesome. +- File a new issue if you run into problems! + +Ground Rules +------------ + +The goal is to maintain a diverse community that's pleasant for +everyone. Please be considerate and respectful of others by following +our `code of +conduct `__. + +- Each pull request should consist of a logical collection of changes. + You can include multiple bug fixes in a single pull request, but they + should be related. For unrelated changes, please submit multiple pull + requests. +- Do not commit changes to files that are irrelevant to your feature or + bug fix (eg: .gitignore). +- Be willing to accept criticism and work on improving your code; we + don’t want to break other users’ code, so care must be taken not to + introduce bugs. +- Be aware that the pull request review process is not immediate, and + is generally proportional to the size of the pull request. +- PRs with new features, or bugfixes, should not fix existing lints. + The more changes in a PR, the harder it will be for the reviewer. We + can always send a separate PR with the lint fix later. +- Avoid making the project “look like your project.” We tend to make + ourselves at home when writing contributions, but we should avoid + renaming things just for renaming sake, moving files around to + “organize” the project, or make aesthetic changes without asking the + upstream devs first. Such changes, while sometimes desirable, don’t + bring much value to a PR but do bring extra burden to the reviewers. +- Do not tackle more than one issue or one feature per PR. While + tempting, the smaller the PR, the easier will be to get it merged, + reducing merge conflicts, without holding other PRs. Many small ones + are always better than a single massive PR. +- Always state your PR objective clearly in the title “New Feature X”, + “Bug Fix Y”, or “Fixing doc typo”. +- Always add a “longer, but not too long, description of your PR in the + body of the first comment. +- Always write meaningful, short, concise, commit messages. The kind of + message your future self will congratulate you. +- When copying code from other places, like Stack-Overflow (SO), always + add the link. That is not only a way to credit the original author of + the code, but also add a way to look for the source when debugging. + Also, it is not uncommon for a SO answer to be updated with better + code. +- When using AI, also add a comment that you did! And, if possible, add + the questions/chat report in a gist and link to it in the PR. While + AI can be of great aid, it can also write obfuscated code that is + hard to debug if you don’t know it was machine generated. +- Be sure to search the existing issues and PRs before submitting + yours. Sometimes these changes are already there and all we need is + an extra person on the hill to make the final push. Be that second + person and not the one that starts a new hill climb by yourself. + Always read the development notes when they exist, many questions are + already answered there. + +Reporting a bug +--------------- + +The easiest way to get involved is to report issues you encounter when +using IOOS Software or by requesting something you think is missing. + +- Head over to the project issues page. +- Search to see if your issue already exists or has even been solved + previously. +- If you indeed have a new issue or request, click the “New Issue” + button. +- Fill in as much of the issue template as is relevant. Please be as + specific as possible. Include the version of the code you were using, + as well as what operating system you are running. If possible, + include complete, minimal example code that reproduces the problem. + +Setting up your development environment +--------------------------------------- + + +Login to your `GitHub `__ account and make a fork of +the repository by clicking the “Fork” button. Clone your fork of the +repository (in terminal on Mac/Linux or git shell/GUI on Windows) to the +location you’d like to keep it. We are partial to creating a +``git_repos`` or ``projects`` directory in our home folder. + +.. code:: sh + + git clone https://github.com/asascience-open/xarray-subset-grid.git + +Pull Requests +------------- + +The changes to the code source (and documentation) should be made via +GitHub pull requests against ``main``, even for those with +administration rights. While it’s tempting to make changes directly to +``main`` and push them up, it is better to make a pull request so that +others can give feedback. If nothing else, this gives a chance for the +automated tests to run on the PR. This can eliminate “brown paper bag” +moments with buggy commits on the main branch. + +Push to your fork and submit a pull request. + +What happens after the pull request +----------------------------------- + +You’ve made your changes, documented them, added some tests, and +submitted a pull request. What now? + +Code Review +~~~~~~~~~~~ + +At this point you’re waiting on us. You should expect to hear at least a +comment within a couple of days. We may suggest some changes or +improvements or alternatives. + +Some things that will increase the chance that your pull request is +accepted quickly: + +- Write tests. +- Fix any failed lints shown by pre-commit-ci. +- Write a `good commit + message `__. + +Pull requests will automatically have tests run by CIs. This includes +running both the unit tests as well as the code linters. The test suite, +documentation, style, and more will be checked on various versions of +Python with current and legacy packages. CIs will run testing on Linux, +and Mac, and Windows. + +Merging +~~~~~~~ + +Once we’re all happy with the pull request, it’s time for it to get +merged in. Only the maintainers can merge pull requests and you should +never merge a pull request you have commits on as it circumvents the +code review. If this is your first or second pull request, we’ll likely +help by rebasing and cleaning up the commit history for you. As your +development skills increase, we’ll help you learn how to do this. + +Further Reading +--------------- + +There are a ton of great resources out there on contributing to open +source and on the importance of writing tested and maintainable +software. + +- `How to Contribute to Open Source + Guide `__ +- `Zen of Scientific Software + Maintenance `__ diff --git a/docs/design.rst b/docs/design.rst new file mode 100644 index 0000000..3d78bc9 --- /dev/null +++ b/docs/design.rst @@ -0,0 +1,36 @@ +.. _design: + +API Design +========== + +The API for this package is very much a work in progress. + +Specifically, there are decisions still to be made around the most efficient way to deal with the xarray accessor: should the grid implementations hold references to the datasets or should they stay static and not require a reference to a given dataset so they can be reused without side effects. + +The grid implementations should also be exposed correctly so that they can be used without the xarray accessor as well. + + +accessor +-------- + +.. automodule:: xarray_subset_grid.accessor + :members: + :undoc-members: + :show-inheritance: + +grid +---- + +.. automodule:: xarray_subset_grid.grid + :members: + :undoc-members: + :show-inheritance: + +utils +----- + +.. automodule:: xarray_subset_grid.utils + :members: + :undoc-members: + :show-inheritance: + diff --git a/examples/README.md b/docs/examples/README.md similarity index 100% rename from examples/README.md rename to docs/examples/README.md diff --git a/examples/example_data/SFBOFS_subset1.nc b/docs/examples/example_data/SFBOFS_subset1.nc similarity index 100% rename from examples/example_data/SFBOFS_subset1.nc rename to docs/examples/example_data/SFBOFS_subset1.nc diff --git a/examples/example_data/small_ugrid_zero_based.nc b/docs/examples/example_data/small_ugrid_zero_based.nc similarity index 100% rename from examples/example_data/small_ugrid_zero_based.nc rename to docs/examples/example_data/small_ugrid_zero_based.nc diff --git a/examples/example_data/stofs_2d_glo.subset.nc b/docs/examples/example_data/stofs_2d_glo.subset.nc similarity index 100% rename from examples/example_data/stofs_2d_glo.subset.nc rename to docs/examples/example_data/stofs_2d_glo.subset.nc diff --git a/examples/example_data/wcofs-subset-control.nc b/docs/examples/example_data/wcofs-subset-control.nc similarity index 100% rename from examples/example_data/wcofs-subset-control.nc rename to docs/examples/example_data/wcofs-subset-control.nc diff --git a/examples/fvcom.ipynb b/docs/examples/fvcom.ipynb similarity index 88% rename from examples/fvcom.ipynb rename to docs/examples/fvcom.ipynb index 970081c..32cd620 100644 --- a/examples/fvcom.ipynb +++ b/docs/examples/fvcom.ipynb @@ -5,7 +5,7 @@ "id": "7866ac9a", "metadata": {}, "source": [ - "# Example: Subset FVCOM dataset given a polygon" + "# FVCOM" ] }, { @@ -14,14 +14,6 @@ "id": "29314777-4fff-4f63-ac75-65620ba193e0", "metadata": {}, "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "/Users/matthew.iannucci/Developer/xarray-subset-grid/venv/lib/python3.10/site-packages/xarray/core/dataset.py:271: UserWarning: The specified chunks separate the stored chunks along dimension \"time\" starting at index 1. This could degrade performance. Instead, consider rechunking after loading.\n", - " warnings.warn(\n" - ] - }, { "data": { "text/html": [ @@ -388,30 +380,30 @@ " stroke: currentColor;\n", " fill: currentColor;\n", "}\n", - "
<xarray.Dataset> Size: 25GB\n",
-       "Dimensions:             (time: 979, four: 4, nele: 569405, node: 303714,\n",
+       "
<xarray.Dataset> Size: 20GB\n",
+       "Dimensions:             (time: 763, four: 4, nele: 569405, node: 303714,\n",
        "                         three: 3, maxnode: 10, maxelem: 8)\n",
        "Coordinates:\n",
        "    lat                 (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
        "    latc                (nele) float32 2MB dask.array<chunksize=(569405,), meta=np.ndarray>\n",
        "    lon                 (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
        "    lonc                (nele) float32 2MB dask.array<chunksize=(569405,), meta=np.ndarray>\n",
-       "  * time                (time) datetime64[ns] 8kB 2024-06-21T21:00:00 ... 202...\n",
+       "  * time                (time) datetime64[ns] 6kB 2024-06-18T21:00:00 ... 202...\n",
        "Dimensions without coordinates: four, nele, node, three, maxnode, maxelem\n",
-       "Data variables: (12/37)\n",
-       "    Times               (time) object 8kB dask.array<chunksize=(1,), meta=np.ndarray>\n",
+       "Data variables: (12/39)\n",
+       "    Itime               (time) datetime64[ns] 6kB dask.array<chunksize=(1,), meta=np.ndarray>\n",
+       "    Times               (time) |S26 20kB dask.array<chunksize=(1,), meta=np.ndarray>\n",
        "    a1u                 (four, nele) float32 9MB dask.array<chunksize=(4, 569405), meta=np.ndarray>\n",
        "    a2u                 (four, nele) float32 9MB dask.array<chunksize=(4, 569405), meta=np.ndarray>\n",
        "    art1                (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
        "    art2                (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
-       "    atmos_press         (time, node) float32 1GB dask.array<chunksize=(1, 303714), meta=np.ndarray>\n",
        "    ...                  ...\n",
-       "    wet_nodes_prev_int  (time, node) int32 1GB dask.array<chunksize=(1, 303714), meta=np.ndarray>\n",
+       "    wet_nodes_prev_int  (time, node) int32 927MB dask.array<chunksize=(1, 303714), meta=np.ndarray>\n",
        "    x                   (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
        "    xc                  (nele) float32 2MB dask.array<chunksize=(569405,), meta=np.ndarray>\n",
        "    y                   (node) float32 1MB dask.array<chunksize=(303714,), meta=np.ndarray>\n",
        "    yc                  (nele) float32 2MB dask.array<chunksize=(569405,), meta=np.ndarray>\n",
-       "    zeta                (time, node) float32 1GB dask.array<chunksize=(1, 303714), meta=np.ndarray>\n",
+       "    zeta                (time, node) float32 927MB dask.array<chunksize=(1, 303714), meta=np.ndarray>\n",
        "Attributes: (12/14)\n",
        "    Conventions:                 CF-1.0\n",
        "    CoordinateProjection:        init=nad83:4205\n",
@@ -420,12 +412,12 @@
        "    River_Forcing:               THERE ARE 63 RIVERS IN THIS MODEL.\\nRIVER IN...\n",
        "    Surface_Heat_Forcing:        FVCOM variable surface heat forcing file:\\nF...\n",
        "    ...                          ...\n",
-       "    Tidal_Forcing:               TIDAL ELEVATION FORCING IS EITHER IN NESTING...\n",
-       "    history:                     model started at: 22/06/2024   04:03\n",
+       "    Tidal_Forcing:               TIDAL ELEVATION FORCING IS OFF!\n",
+       "    history:                     model started at: 18/06/2024   21:15\n",
        "    institution:                 School for Marine Science and Technology\n",
-       "    references:                  http://fvcom.smast.umassd.edu, https://githu...\n",
-       "    source:                      FVCOM_4.4.7\n",
-       "    title:                       NGOFS2