📚 Documentation cleanup

docs/environment.yml

@@ -6,6 +6,7 @@ dependencies:
   - dask
   - fsspec
   - jupyterlab
+  - linkify-it-py
   - matplotlib
   - myst-nb
   - netcdf4
@@ -15,7 +16,7 @@ dependencies:
   - python=3.8
   - sphinx-book-theme >= 0.0.38
   - sphinx-copybutton
-  - sqlalchemy==1.3.12
+  - sqlalchemy<1.4
   - tqdm
   - watermark
   - xarray

docs/source/conf.py

@@ -36,7 +36,18 @@
 ]
 
 # MyST config
-myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image']
+myst_enable_extensions = [
+    'amsmath',
+    'colon_fence',
+    'deflist',
+    'dollarmath',
+    'html_admonition',
+    'html_image',
+    'linkify',
+    'replacements',
+    'smartquotes',
+    'substitution',
+]
 myst_url_schemes = ('http', 'https', 'mailto')
 
 # sphinx-copybutton configurations

docs/source/examples/CloseHeatBudget_POP2.ipynb

@@ -6,11 +6,10 @@
    "source": [
     "# Calculate POP2 heat budget using xgcm\n",
     "\n",
-    "Contributed by Anna-Lena Deppenmeier\n",
+    "In this notebook, we are going to use xgcm with metrics to demonstrate budget closure. This notebook was contributed by [Anna-Lena Deppenmeier](https://github.com/ALDepp).\n",
     "\n",
-    "Using xgcm with metric to demonstrate budget closure. \n",
     "\n",
-    "This is an image of the POP output structure on the horizontal B-grid courtesy Yassir Eddebbar\n",
+    "This is an image of the POP output structure on the horizontal B-grid courtesy of [Yassir Eddebbar](https://github.com/Eddebbar).\n",
     "\n",
     "<img src=\"POP_Grid.png\" alt=\"Drawing\" style=\"width: 800px;\"/>"
    ]

docs/source/examples/lateral-fill-idealized.ipynb

@@ -6,7 +6,14 @@
    "source": [
     "# Lateral fill concept\n",
     "\n",
-    "When regidding datasets for initial conditions, it is necessary to ensure that all model points have data. In many cases, differences between land-sea masks yield regions along the margins that require filling. The `pop_tools.lateral_fill_np_array` routine applies an iterative filling procedure to accomplish this. This is illustrated here."
+    "When regidding datasets for initial conditions, it is necessary to ensure that all model points have data. In many cases, differences between land-sea masks yield regions along the margins that require filling. The {py:func}`~pop_tools.lateral_fill_np_array` routine applies an iterative filling procedure to accomplish this. This is illustrated here."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import packages"
    ]
   },
   {

docs/source/examples/lateral-fill-model-grid.ipynb

@@ -6,7 +6,14 @@
    "source": [
     "# Lateral fill on model grid\n",
     "\n",
-    "This example shows how to apply `pop_tools.lateral_fill` on a model dataset. We use a model grid dataset for illustration purposes."
+    "This example shows how to apply {py:func}`~pop_tools.lateral_fill` on a model dataset. We use a model grid dataset for illustration purposes."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import packages"
    ]
   },
   {

docs/source/examples/pop_div_curl_xr_xgcm_metrics_compare.ipynb

@@ -14,7 +14,17 @@
     "\n",
     "3) use [`xgcm.get_metric`](https://xgcm.readthedocs.io/en/latest/grid_metrics.html) capabilities to simplify the code. \n",
     "\n",
-    "The ``metrics`` functionality lets us write generalized ``div``, ``grad`` and ``curl`` functions that should be available in ``xgcm`` in the future (see [xgcm/xgcm #187](https://github.com/xgcm/xgcm/issues/187))"
+    "The ``metrics`` functionality lets us write generalized ``div``, ``grad`` and ``curl`` functions that should be available in ``xgcm`` in the future (see [xgcm/xgcm #187](https://github.com/xgcm/xgcm/issues/187)). \n",
+    "\n",
+    "\n",
+    "This notebook was contributed by [Anna-Lena Deppenmeier](https://github.com/ALDepp)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import packages"
    ]
   },
   {
@@ -688,7 +698,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`ds_re`n contains all variables from `ds`, but ```nlat/nlon``` have been replaced by ```nlat_t/nlon_t``` and ```nlat_u/nlon_u``` depending on which points the variables are at:"
+    "`ds_ren` contains all variables from `ds`, but ```nlat/nlon``` have been replaced by ```nlat_t/nlon_t``` and ```nlat_u/nlon_u``` depending on which points the variables are at:"
    ]
   },
   {

docs/source/examples/region-mask.ipynb

@@ -10,6 +10,13 @@
     "relevant for analyses. `pop_tools` provides several alternative region masks; these are demostrated here."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import packages"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/source/examples/sample-data.ipynb

@@ -13,7 +13,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Where are my data files?\n",
+    "## Where are the sample data files?\n",
     "\n",
     "The sample data files are downloaded automatically by [pooch](https://www.fatiando.org/pooch/latest/api/index.html#module-pooch) the first time you load them. \n"
    ]