Add stubs for circulation models, and docstrings for hycom and nemo

Author: VeckoTheGecko

parcels/_datasets/__init__.py

@@ -3,7 +3,7 @@
 
 This subpackage uses xarray to generate *idealised* structured and unstructured hydrodynamical datasets that are compatible with Parcels. The goals are three-fold:
 
-1. To provide users with documentation for the types of datasets they can expect Parcels to work with.
+1. To provide users with documentation for the types of datasets they can expect Parcels to work with. When reporting bugs, users can use these datasets to reproduce the bug they're experiencing (allowing developers to quickly troubleshoot the problem).
 2. To supply our tutorials with hydrodynamical datasets.
 3. To offer developers datasets for use in test cases.
 
@@ -36,8 +36,10 @@
 
 This subpackage is broken down into structured and unstructured parts. Each of these have common submodules:
 
-* ``circulation_model`` -> hardcoded datasets with the intention of mimicking dataset structure from a certain (ocean) circulation model
+* ``circulation_model`` -> hardcoded datasets with the intention of mimicking dataset structure from a certain (ocean) circulation model. If you'd like to see Parcel support a new model, please open an issue in our issue tracker.
+    * exposes a dict ``datasets`` mapping dataset names to xarray datasets
 * ``generic`` -> hardcoded datasets that are generic, and not tied to a certain (ocean) circulation model. Instead these focus on the fundamental properties of the dataset
+    * exposes a dict ``datasets`` mapping dataset names to xarray datasets
 * ``generated`` -> functions to generate datasets with varying properties
 * ``utils`` -> any utility functions necessary related to either generating or validating datasets
 

parcels/_datasets/structured/circulation_model.py

@@ -1,11 +1,40 @@
 import xarray as xr
 
+from . import T, X, Y, Z
+
+__all__ = ["T", "X", "Y", "Z", "datasets"]
+
 
 def _nemo_data() -> xr.Dataset:
-    """Dataset matching NEMO model output.
+    """Dataset matching level 0 NEMO model output.
 
-    Example dataset is based off of data from MOi GLO12.
+    Example dataset is based off of data from the MOi GLO12 run.
 
     https://www.mercator-ocean.eu/en/solutions-expertise/accessing-digital-data/product-details/?offer=4217979b-2662-329a-907c-602fdc69c3a3&system=d35404e4-40d3-59d6-3608-581c9495d86a
     """
     ...
+
+
+def _hycom_data() -> xr.Dataset:
+    """Dataset matching level 0 HYCOM model output.
+
+    Example dataset is based off of data from the GOFS 3.1: 41-layer HYCOM + NCODA Global 1/12° Analysis.
+
+    https://www.hycom.org/dataserver/gofs-3pt1/analysis
+    """
+    ...
+
+
+def _mitgcm_data() -> xr.Dataset: ...
+
+
+def _pop_data() -> xr.Dataset: ...
+
+
+def _echo_data() -> xr.Dataset: ...
+
+
+def _croco_data() -> xr.Dataset: ...
+
+
+datasets = {}