docs: move notebooks and use myst

fix: correct error when using default bounds in `extract_constants` for #356 fix: correct `TPXO10-atlas-v2` binary grid filename refactor: use `setuptools` entry points for scripts
tsutterley · Oct 31, 2024 · c998fe2 · c998fe2
1 parent 5c4bca1
commit c998fe2
Show file tree

Hide file tree

Showing 46 changed files with 321 additions and 225 deletions.
diff --git a/doc/environment.yml b/doc/environment.yml
@@ -7,6 +7,7 @@ dependencies:
   - freetype
   - graphviz
   - lxml
+  - myst-nb
   - netCDF4
   - numpy
   - numpydoc

diff --git a/doc/source/api_reference/arcticdata_tides.rst b/doc/source/api_reference/arcticdata_tides.rst
@@ -12,7 +12,7 @@ arcticdata_tides.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/arcticdata_tides.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/arcticdata_tides.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/aviso_fes_tides.rst b/doc/source/api_reference/aviso_fes_tides.rst
@@ -9,7 +9,7 @@ aviso_fes_tides.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/aviso_fes_tides.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/aviso_fes_tides.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_LPET_elevations.rst b/doc/source/api_reference/compute_LPET_elevations.rst
@@ -8,7 +8,7 @@ compute_LPET_elevation.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_LPET_elevations.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_LPET_elevations.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_LPT_displacements.rst b/doc/source/api_reference/compute_LPT_displacements.rst
@@ -9,7 +9,7 @@ compute_LPT_displacements.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_LPT_displacements.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_LPT_displacements.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_OPT_displacements.rst b/doc/source/api_reference/compute_OPT_displacements.rst
@@ -10,7 +10,7 @@ compute_OPT_displacements.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_OPT_displacements.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_OPT_displacements.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_SET_displacements.rst b/doc/source/api_reference/compute_SET_displacements.rst
@@ -9,7 +9,7 @@ compute_SET_displacements.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_SET_displacements.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_SET_displacements.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_tidal_currents.rst b/doc/source/api_reference/compute_tidal_currents.rst
@@ -9,7 +9,7 @@ compute_tidal_currents.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_tidal_currents.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_tidal_currents.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/compute_tidal_elevations.rst b/doc/source/api_reference/compute_tidal_elevations.rst
@@ -10,7 +10,7 @@ compute_tidal_elevations.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_tidal_elevations.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_tidal_elevations.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/gsfc_got_tides.rst b/doc/source/api_reference/gsfc_got_tides.rst
@@ -13,7 +13,7 @@ gsfc_got_tides.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/gsfc_got_tides.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/gsfc_got_tides.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/reduce_OTIS_files.rst b/doc/source/api_reference/reduce_OTIS_files.rst
@@ -6,7 +6,7 @@ reduce_OTIS_files.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/reduce_OTIS_files.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/reduce_OTIS_files.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/usap_cats_tides.rst b/doc/source/api_reference/usap_cats_tides.rst
@@ -9,7 +9,7 @@ usap_cats_tides.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/usap_cats_tides.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/usap_cats_tides.py
 
 Calling Sequence
 ################

diff --git a/doc/source/api_reference/verify_box_tpxo.rst b/doc/source/api_reference/verify_box_tpxo.rst
@@ -7,7 +7,7 @@ verify_box_tpxo.py
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/scripts/verify_box_tpxo.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/verify_box_tpxo.py
 
 Calling Sequence
 ################

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -40,11 +40,19 @@
 extensions = [
     "sphinx.ext.autodoc",
     "numpydoc",
+    "myst_nb",
     "sphinx.ext.graphviz",
     "sphinx.ext.viewcode",
     "sphinxarg.ext"
 ]
 
+# use myst for notebooks
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+}
+nb_execution_mode = "off"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst
@@ -12,12 +12,12 @@ Ocean and load tide constituent files are available from different modeling grou
 ``pyTMD`` can access the harmonic constituents for the OTIS, GOT and FES families of ocean and load tide models.
 OTIS and ATLAS formatted data use  binary files to store the constituent data for either heights (``z``) or zonal and meridional transports (``u``, ``v``).
 They can be either a single file containing all the constituents (compact) or multiple files each containing a single constituent.
-Arctic Ocean models can be downloaded from the NSF ArcticData server using the `arcticdata_tides.py <https://github.com/tsutterley/pyTMD/blob/main/scripts/arcticdata_tides.py>`_ program.
-CATS2008 can be downloaded from the US Antarctic Program (USAP) using the `usap_cats_tides.py <https://github.com/tsutterley/pyTMD/blob/main/scripts/usap_cats_tides.py>`_ program.
+Arctic Ocean models can be downloaded from the NSF ArcticData server using the `arcticdata_tides.py <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/arcticdata_tides.py>`_ program.
+CATS2008 can be downloaded from the US Antarctic Program (USAP) using the `usap_cats_tides.py <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/usap_cats_tides.py>`_ program.
 ATLAS netCDF formatted data use netCDF4 files for each constituent and variable type (``z``, ``u``, ``v``).
 GOT formatted data use ascii files for each height constituent (``z``).
 FES formatted data use either ascii (1999, 2004) or netCDF4 (2012, 2014) files for each constituent and variable type (``z``, ``u``, ``v``).
-The FES models can be downloaded using the `aviso_fes_tides.py <https://github.com/tsutterley/pyTMD/blob/main/scripts/aviso_fes_tides.py>`_ program for users registered with AVISO.
+The FES models can be downloaded using the `aviso_fes_tides.py <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/aviso_fes_tides.py>`_ program for users registered with AVISO.
 
 Model Database
 ##############
@@ -117,8 +117,8 @@ compute the corresponding tidal elevation or currents.
 
 
 For users wanting to calculate tidal elevations or currents for a series of files, the
-`compute_tidal_elevations.py <https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_tidal_elevations.py>`_ and
-`compute_tidal_currents.py <https://github.com/tsutterley/pyTMD/blob/main/scripts/compute_tidal_currents.py>`_ programs
+`compute_tidal_elevations.py <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_tidal_elevations.py>`_ and
+`compute_tidal_currents.py <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/src/compute_tidal_currents.py>`_ programs
 cover most use cases.  They take an input file (in csv, netCDF4, HDF5, parquet or geotiff formats) and compute the tidal
 elevations or currents (zonal and meridional) for each point.
 

diff --git a/notebooks/Check Tide Map.ipynb → doc/source/notebooks/Check-Tide-Map.ipynb b/notebooks/Check Tide Map.ipynb → doc/source/notebooks/Check-Tide-Map.ipynb
@@ -8,27 +8,29 @@
     "Check Tide Map\n",
     "==============\n",
     "\n",
-    "Check if a given point is within a tide model domain\n",
+    "This ({nb-download}`notebook <Check-Tide-Map.ipynb>`) demonstrates checking if given points are within a tide model domain\n",
     "\n",
     "OTIS format tidal solutions provided by Oregon State University and ESR  \n",
-    "- http://volkov.oce.orst.edu/tides/region.html  \n",
-    "- https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/\n",
-    "- ftp://ftp.esr.org/pub/datasets/tmd/  \n",
+    "- [http://volkov.oce.orst.edu/tides/region.html](http://volkov.oce.orst.edu/tides/region.html) \n",
+    "- [https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/](https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/)\n",
+    "- [ftp://ftp.esr.org/pub/datasets/tmd/](ftp://ftp.esr.org/pub/datasets/tmd/)  \n",
     "\n",
     "Global Tide Model (GOT) solutions provided by Richard Ray at GSFC  \n",
+    "- [https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models](https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models)\n",
     "\n",
     "Finite Element Solution (FES) provided by AVISO  \n",
-    "- https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html\n",
+    "- [https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html\n",
+    ")\n",
     "\n",
-    "#### Python Dependencies\n",
+    "## Python Dependencies\n",
     " - [numpy: Scientific Computing Tools For Python](https://www.numpy.org)  \n",
     " - [scipy: Scientific Tools for Python](https://www.scipy.org/)  \n",
     " - [pyproj: Python interface to PROJ library](https://pypi.org/project/pyproj/)  \n",
     " - [netCDF4: Python interface to the netCDF C library](https://unidata.github.io/netcdf4-python/)  \n",
     " - [matplotlib: Python 2D plotting library](https://matplotlib.org/)  \n",
     " - [ipyleaflet: Jupyter / Leaflet bridge enabling interactive maps](https://github.com/jupyter-widgets/ipyleaflet)  \n",
     "\n",
-    "#### Program Dependencies\n",
+    "## Program Dependencies\n",
     "\n",
     "- `crs.py`: Coordinate Reference System (CRS) routines\n",
     "- `io.model.py`: retrieves tide model parameters for named tide models\n",
@@ -44,7 +46,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Load modules"
+    "## Load modules"
    ]
   },
   {
@@ -69,6 +71,16 @@
     "%autoreload 2"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Set parameters for program\n",
+    "\n",
+    "- Model directory  \n",
+    "- Tide model  "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -88,6 +100,13 @@
     "])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Select location to check"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -102,6 +121,13 @@
     "m.map"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Read and create mask of valid model values"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -200,6 +226,13 @@
     "    IPython.display.display(m.figure)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot mask and selected location"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

diff --git a/notebooks/Plot ATLAS Compact.ipynb → ...source/notebooks/Plot-ATLAS-Compact.ipynb b/notebooks/Plot ATLAS Compact.ipynb → ...source/notebooks/Plot-ATLAS-Compact.ipynb
@@ -8,19 +8,20 @@
     "Plot ATLAS Compact\n",
     "==================\n",
     "\n",
-    "Check if a given point is within a tide model domain\n",
+    "This ({nb-download}`notebook <Plot-ATLAS-Compact.ipynb>`) demonstrates plotting the global and local solutions from an ATLAS compact model\n",
     "\n",
     "OTIS format tidal solutions provided by Oregon State University and ESR  \n",
-    "- http://volkov.oce.orst.edu/tides/region.html  \n",
+    "- [http://volkov.oce.orst.edu/tides/region.html](http://volkov.oce.orst.edu/tides/region.html) \n",
     "\n",
-    "#### Python Dependencies\n",
+    "\n",
+    "## Python Dependencies\n",
     " - [numpy: Scientific Computing Tools For Python](https://www.numpy.org)  \n",
     " - [scipy: Scientific Tools for Python](https://www.scipy.org/)  \n",
     " - [pyproj: Python interface to PROJ library](https://pypi.org/project/pyproj/)  \n",
     " - [netCDF4: Python interface to the netCDF C library](https://unidata.github.io/netcdf4-python/)  \n",
     " - [matplotlib: Python 2D plotting library](https://matplotlib.org/)  \n",
     "\n",
-    "#### Program Dependencies\n",
+    "## Program Dependencies\n",
     "\n",
     "- `io.model.py`: retrieves tide model parameters for named tide models\n",
     "- `io.OTIS.py`: extract tidal harmonic constants from OTIS tide models  \n",
@@ -32,7 +33,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Load modules"
+    "## Load modules"
    ]
   },
   {
@@ -54,6 +55,16 @@
     "%autoreload 2"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Set parameters for program\n",
+    "\n",
+    "- Model directory  \n",
+    "- Tide model  "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -74,6 +85,13 @@
     "])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup tide model parameters"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -88,6 +106,13 @@
     "constituents,nc = pyTMD.io.OTIS.read_constituents(model.model_file)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Read ATLAS Compact model"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -102,6 +127,13 @@
     "x30,y30,hz30 = pyTMD.io.OTIS.interpolate_atlas_model(x0,y0,hz0)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot global and local masks"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -127,6 +159,13 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot differences between global and local solutions"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,