Add documentation skeleton (#268)

* Add documentation skeleton

* further improvements

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply suggestions from code review

Co-authored-by: Martin Yeo <40734014+trexfeathers@users.noreply.github.com>

* address review comments

* address review comments

* clarify how quick links refers to structure

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Martin Yeo <40734014+trexfeathers@users.noreply.github.com>

README.md

@@ -11,8 +11,6 @@
 
 ---
 
-[Click here for the API documentation](https://iris-esmf-regrid.readthedocs.io/en/latest)
-
 ## Overview
 
 This project aims to provide a bridge between [Iris](https://github.com/SciTools/iris)
@@ -22,47 +20,4 @@ calculations. These classes are designed to perform well on cubes which have mul
 non-horizontal dimensions and lazy ([Dask](https://github.com/dask/dask)) data.
 Both rectilinear and curvilinear grids as well as UGRID meshes have been supported.
 
-## Regridding Example
-
-There are a range of regridder classes (e.g `MeshToGridESMFRegridder` and
-`GridToMeshESMFRegridder`). For an example of the regridding process, the
-`MeshToGridESMFRegridder` class works as follows:
-
-```python
-import iris
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-from esmf_regrid.experimental.unstructured_scheme import MeshToGridESMFRegridder
-
-# An example such a file can be found at:
-# https://github.com/SciTools/iris-test-data/blob/master/test_data/NetCDF/unstructured_grid/data_C4.nc
-with PARSE_UGRID_ON_LOAD.context():
-    source_mesh_cube = iris.load_cube("mesh_cube.nc")
-
-# An example of such a file can be found at:
-# https://github.com/SciTools/iris-test-data/blob/master/test_data/NetCDF/global/xyt/SMALL_hires_wind_u_for_ipcc4.nc
-target_grid_cube = iris.load_cube("grid_cube.nc")
-
-# Initialise the regridder with a source mesh and target grid.
-regridder = MeshToGridESMFRegridder(source_mesh_cube, target_grid_cube)
-
-# use the initialised regridder to regrid the data from the source cube
-# onto a cube with the same grid as `target_grid_cube`.
-result = regridder(source_mesh_cube)
-```
-
-Note that this pattern allows the reuse of an initialised regridder, saving
-significant amounts of time when regridding. To make use of this efficiency across
-sessions, we support the saving of certain regridders. We can do this as follows:
-
-```python
-from esmf_regrid.experimental.io import load_regridder, save_regridder
-
-# Save the regridder.
-save_regridder(regridder, "saved_regridder.nc")
-
-# Load saved regridder.
-loaded_regridder = load_regridder("saved_regridder.nc")
-
-# Use loaded regridder.
-result = loaded_regridder(source_mesh_cube)
-```
+Further documentation can be found [here](https://iris-esmf-regrid.readthedocs.io/en/latest).

docs/src/conf.py

@@ -7,6 +7,7 @@
 from datetime import datetime
 import os
 from pathlib import Path
+import re
 import sys
 
 # -- Path setup --------------------------------------------------------------
@@ -66,6 +67,36 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
+def _dotv(version):
+    result = version
+    match = re.match(r"^py(\d+)$", version)
+    if match:
+        digits = match.group(1)
+        if len(digits) > 1:
+            result = f"{digits[0]}.{digits[1:]}"
+    return result
+
+
+# Automate the discovery of the python versions tested with CI.
+python_support = sorted(
+    [fname.stem for fname in Path(".").glob("../../requirements/py*.yml")]
+)
+
+
+if not python_support:
+    python_support = "unknown Python versions"
+elif len(python_support) == 1:
+    python_support = f"Python {_dotv(python_support[0])}"
+else:
+    rest = ", ".join([_dotv(v) for v in python_support[:-1]])
+    last = _dotv(python_support[-1])
+    python_support = f"Python {rest} and {last}"
+
+rst_epilog = f"""
+.. |python_support| replace:: {python_support}
+"""
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -86,10 +117,10 @@
 }
 
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# # Add any paths that contain custom static files (such as style sheets) here,
+# # relative to this directory. They are copied after the builtin static files,
+# # so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
 
 
 # -- api generation configuration ---------------------------------------------

docs/src/developers_guide/index.rst

@@ -0,0 +1,4 @@
+Developers Guide
+================
+
+This section has not yet been written.

docs/src/index.rst

@@ -1,18 +1,44 @@
 iris-esmf-regrid
 ================
 
-A collection of structured and unstructured ESMF_ regridding schemes for Iris_.
+Iris-esmf-regrid is a package which aims to bridge the gap between Iris_ data
+handling and ESMF_ regridding. This is done largely by way of providing
+Iris_-like regridding schemes.
 
-This rendered documentation is so far limited to iris-esmf-regrid's API. Some
-basic examples and change logs can be found on GitHub_.
+This documentation is a work in progress and some pages will be incomplete.
+In the mean time, the following quick links point to useful pages in the user
+guide and API sections.
 
-:doc:`Click to view the API<_api_generated/modules>`
+Quick Links
+-----------
+
+How-to
+^^^^^^
+
+- For examples of code, see the :doc:`examples page<userguide/examples>`
+  in the user guide.
+
+Understand how iris-esmf-works
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- For a breakdown of the objects which exist in iris-esmf-regrid, see the
+  :doc:`scheme comparison page<userguide/scheme_comparison>` in the user
+  guide.
+
+Reference
+^^^^^^^^^
+
+- For a full description of each object, see the
+  :doc:`API section<_api_generated/modules>`.
 
 .. toctree::
    :hidden:
 
+   installing
+   userguide/index
+   developers_guide/index
    _api_generated/modules
+   whatsnew/index
 
 .. _Iris: https://github.com/SciTools/iris
 .. _ESMF: https://github.com/esmf-org/esmf
-.. _GitHub: https://github.com/SciTools-incubator/iris-esmf-regrid

docs/src/installing.rst

@@ -0,0 +1,27 @@
+Installing
+==========
+
+Iris is available using conda for the following platforms:
+
+* Linux 64-bit,
+* Mac OSX 64-bit, and
+* Windows 64-bit.
+
+.. note:: Iris-esmf-regrid is currently supported and tested against
+          |python_support| running on Linux.  We do not currently
+          actively test on other platforms such as Windows or macOS.
+
+
+.. _installing_using_conda:
+
+Installing Using Conda
+----------------------
+
+To install Iris-esmf-regrid using conda, you must first download and install
+conda, for example from https://docs.conda.io/en/latest/miniconda.html.
+
+Once conda is installed, you can install Iris-esmf-regrid using conda with
+the following command::
+
+  conda install -c conda-forge iris-esmf-regrid
+

docs/src/userguide/examples.rst

@@ -0,0 +1,60 @@
+Examples
+========
+
+Simple Regridding
+-----------------
+
+To regrid a single Iris_ cube using an area-weighted conservative method::
+
+    import iris
+    from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
+    from esmf_regrid.schemes import ESMFAreaWeighted
+
+    # An example such a file can be found at:
+    # https://github.com/SciTools/iris-test-data/blob/master/test_data/NetCDF/unstructured_grid/data_C4.nc
+    with PARSE_UGRID_ON_LOAD.context():
+        source_mesh_cube = iris.load_cube("mesh_cube.nc")
+
+    # An example of such a file can be found at:
+    # https://github.com/SciTools/iris-test-data/blob/master/test_data/NetCDF/global/xyt/SMALL_hires_wind_u_for_ipcc4.nc
+    target_grid_cube = iris.load_cube("grid_cube.nc")
+
+    result = source_mesh_cube.regrid(target_grid_cube, ESMFAreaWeighted())
+
+Note that this scheme is flexible and it is also possible to regrid from
+a structured cube to an unstructured cube as follows::
+
+    result = target_grid_cube.regrid(source_mesh_cube, ESMFAreaWeighted())
+
+Saving and Loading a Regridder
+------------------------------
+A regridder can be set up for reuse, this saves time performing the
+computationally expensive initialisation process::
+
+    from esmf_regrid.experimental.unstructured_scheme import MeshToGridESMFRegridder
+
+    # Initialise the regridder with a source mesh and target grid.
+    regridder = MeshToGridESMFRegridder(source_mesh_cube, target_grid_cube)
+
+    # use the initialised regridder to regrid the data from the source cube
+    # onto a cube with the same grid as `target_grid_cube`.
+    result = regridder(source_mesh_cube)
+
+To make use of this efficiency across sessions, we support the saving of
+certain regridders. We can do this as follows::
+
+    from esmf_regrid.experimental.io import load_regridder, save_regridder
+
+    # Save the regridder.
+    save_regridder(regridder, "saved_regridder.nc")
+
+    # Load saved regridder.
+    loaded_regridder = load_regridder("saved_regridder.nc")
+
+    # Use loaded regridder.
+    result = loaded_regridder(source_mesh_cube)
+
+.. todo:
+    Add more examples.
+
+.. _Iris: https://github.com/SciTools/iris

docs/src/userguide/index.rst

@@ -0,0 +1,8 @@
+User Guide
+==========
+
+.. toctree::
+
+   examples
+   scheme_comparison
+   tutorials

docs/src/userguide/scheme_comparison.rst

@@ -0,0 +1,90 @@
+Scheme Comparison
+=================
+
+There are a number of objects which can be used to regrid Iris_ cubes.
+These each have their own quirks which this page aims to describe.
+
+Overview: Schemes
+-----------------
+
+The top level objects provided by iris-esmf-regrid as the *schemes*,
+these are designed to behave the same as the *schemes* in
+:py:mod:`iris.analysis`. The three schemes iris-esmf-regrid provides
+are :class:`~esmf_regrid.schemes.ESMFAreaWeighted`,
+:class:`~esmf_regrid.schemes.ESMFBilinear` and
+:class:`~esmf_regrid.schemes.ESMFNearest`. These wrap the ESMF_
+regrid methods :attr:`~esmpy.api.constants.RegridMethod.CONSERVE`,
+:attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+:attr:`~esmpy.api.constants.RegridMethod.NEAREST_STOD` respectively.
+The schemes can be by the pattern::
+
+    result_cube = source_cube.regrid(target_cube, ESMFAreaWeighted())
+
+These schemes are flexible and allow the source or target cube to be
+defined on an unstructured mesh while the other cube is define on a
+structured grid.
+
+Overview: Regridders
+--------------------
+
+The *regridders* are objects one level down from schemes. A regridder
+is a class which is designed to handle the regridding of data from
+one specific source to one specific target. *Regridders* are useful
+because regridding involves a computationally expensive intitialisation
+step which can be avoided whenever a *regridder* is reused.
+iris-esmf-regrid provides the regridders
+:class:`~esmf_regrid.schemes.ESMFAreaWeightedRegridder`,
+:class:`~esmf_regrid.schemes.ESMFBilinearRegridder` and
+:class:`~esmf_regrid.schemes.ESMFNearestRegridder` which correspond to
+the schemes :class:`~esmf_regrid.schemes.ESMFAreaWeighted`,
+:class:`~esmf_regrid.schemes.ESMFBilinear` and
+:class:`~esmf_regrid.schemes.ESMFNearest` respectively.
+These can be initialised either by::
+
+    regridder = ESMFAreaWeightedRegridder(source_cube, target_cube)
+
+or equivalently by::
+
+    regridder = ESMFAreaWeighted().regridder(source_cube, target_cube)
+
+This regridder can then be called by::
+
+    result_cube = regridder(source_cube, target_cube)
+
+which can be reused on any cube defined on the same horizontal
+coordinates as ``source_cube``.
+
+There are also the experimental regridders
+:class:`~esmf_regrid.experimental.unstructured_scheme.MeshToGridESMFRegridder` and
+:class:`~esmf_regrid.experimental.unstructured_scheme.GridToMeshESMFRegridder`.
+These were formerly the only way to do regridding with a source or
+target cube defined on an unstructured mesh. These are less flexible and
+require that the source/target be defined on a grid/mesh. Unlike the above
+regridders whose method is fixed, these regridders take a ``method`` keyword
+of ``conservative``, ``bilinear`` or ``nearest``. While most of the
+functionality in these regridders have been ported into the above schemes and
+regridders, these remain the only regridders capable of being saved and loaded by
+:mod:`esmf_regrid.experimental.io`.
+
+
+Overview: Miscellaneous Functions
+---------------------------------
+
+The functions :func:`~esmf_regrid.schemes.regrid_rectilinear_to_rectilinear`,
+:func:`~esmf_regrid.experimental.unstructured_scheme.regrid_unstructured_to_rectilinear` and
+:func:`~esmf_regrid.experimental.unstructured_scheme.regrid_rectilinear_to_unstructured`
+exist as alternative ways to call the same regridding functionality::
+
+    result = regrid_rectilinear_to_rectilinear(source_cube, target_cube)
+
+This function also has a ``method`` keyword which can be ``conservative``, ``bilinear``
+or ``nearest``, with ``conservative`` being the default.
+
+Differences Between Methods
+---------------------------
+
+This section is under development, for more details see the
+:doc:`API documentation<../_api_generated/modules>`.
+
+.. _Iris: https://github.com/SciTools/iris
+.. _ESMF: https://github.com/esmf-org/esmf

docs/src/userguide/tutorials.rst

@@ -0,0 +1,4 @@
+Tutorials
+=========
+
+This section has not yet been written.

docs/src/whatsnew/index.rst

@@ -0,0 +1,7 @@
+What's New?
+===========
+
+A proper whatsnew is under development, please consult the Changelog_.
+
+
+.. _Changelog: https://github.com/SciTools-incubator/iris-esmf-regrid/blob/main/CHANGELOG.md

esmf_regrid/__init__.py

@@ -10,4 +10,4 @@
 from .schemes import *
 
 
-__version__ = "0.6.0"
+__version__ = "0.7.dev0"