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
tsutterley · Oct 31, 2024 · d7d8c6a · d7d8c6a
1 parent 5c4bca1
commit d7d8c6a
Show file tree

Hide file tree

Showing 20 changed files with 290 additions and 203 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/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/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,

diff --git a/...books/Plot Antarctic Cotidal Charts.ipynb → ...books/Plot-Antarctic-Cotidal-Charts.ipynb b/...books/Plot Antarctic Cotidal Charts.ipynb → ...books/Plot-Antarctic-Cotidal-Charts.ipynb
@@ -8,27 +8,28 @@
     "Plot Antarctic Cotidal Charts\n",
     "=============================\n",
     "\n",
-    "Demonstrates plotting cotidal charts around Antarctica\n",
+    "This ({nb-download}`notebook <Plot-Antarctic-Cotidal-Charts.ipynb>`) demonstrates plotting cotidal charts for selected constituents around Antarctica\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",
-    "#### 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](http://matplotlib.org/)  \n",
     " - [cartopy: Python package designed for geospatial data processing](https://scitools.org.uk/cartopy/docs/latest/)  \n",
     "\n",
-    "#### Program Dependencies\n",
+    "## Program Dependencies\n",
     "\n",
     "- `arguments.py`: load the nodal corrections for tidal constituents  \n",
     "- `astro.py`: computes the basic astronomical mean longitudes  \n",
@@ -49,7 +50,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Load modules"
+    "## Load modules"
    ]
   },
   {
@@ -80,7 +81,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Set parameters  for program\n",
+    "## Set parameters for program\n",
     "\n",
     "- Model directory  \n",
     "- Tide model  "
@@ -109,7 +110,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Setup tide model parameters"
+    "## Setup tide model parameters"
    ]
   },
   {
@@ -128,7 +129,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Setup coordinates for calculating tidal amplitudes"
+    "## Setup coordinates for calculating tidal amplitudes"
    ]
   },
   {
@@ -159,7 +160,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Calculate tide map"
+    "## Calculate tide map"
    ]
   },
   {
@@ -192,7 +193,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Select constituent for cotidal chart"
+    "## Select constituent for cotidal chart"
    ]
   },
   {
@@ -210,7 +211,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Create cotidal chart"
+    "## Create cotidal chart"
    ]
   },
   {
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,7 @@ dependencies: @@
       - freetype
       - graphviz
       - lxml
+      - myst-nb
       - netCDF4
       - numpy
       - numpydoc
@@ Expand Down @@