MODFLOW-ORG · wpbonelli · Feb 7, 2024 · Dec 13, 2023 · Jan 21, 2024 · Jan 22, 2024
diff --git a/.doc/conf.py b/.doc/conf.py
@@ -12,9 +12,13 @@
 #
 import os
 import re
+from modflow_devtools.misc import get_env
 
 # -- set boolean indicating if running on readthedocs server -----------------
-on_rtd = os.environ.get("READTHEDOCS") == "True"
+on_rtd = get_env("READTHEDOCS", False)
+
+# -- get git ref from which we are building the docs -------------------------
+ref = get_env("READTHEDOCS_GIT_IDENTIFIER", "master")
 
 # -- setup regular expression for body.tex -----------------------------------
 ex_regex = re.compile("\\\\input{sections/(.*?)\\}")
@@ -32,37 +36,23 @@
         gwt_list.append(v.replace(".tex", ""))
 
 # -- Build examples.rst for notebooks to .doc --------------------------------
-f = open("notebook_examples.rst", "w")
-
-lines = "MODFLOW 6 Examples - Jupyter Notebooks\n"
-lines += (len(lines) - 1) * "-" + "\n\n"
-lines += (
-    "The Jupyter Notebooks used to create the input files and figures for \n"
-    + "each of the MODFLOW 6 `examples <examples.html>`_.\n\n"
-)
-f.write(lines)
-
-# gwf examples Jupyter Notebooks
-lines = ".. toctree::\n"
-lines += "   :numbered:\n"
-lines += "   :maxdepth: 1\n\n"
-for base_name in gwf_list:
-    lines += f"   {base_name} "
-    lines += "<{}>\n".format(os.path.join("_notebooks", base_name + ".ipynb"))
-for base_name in gwt_list:
-    lines += f"   {base_name} "
-    lines += "<{}>\n".format(os.path.join("_notebooks", base_name + ".ipynb"))
-lines += "\n\n"
-f.write(lines)
-
-# close the restructured text file
-f.close()
-
-# # -- convert the tutorial scripts -------------------------------------------
-# if not on_rtd:
-#     cmd = ("python", "test_build.py")
-#     print(" ".join(cmd))
-#     os.system(" ".join(cmd))
+with open("notebook_examples.rst", "w") as f:
+    lines = "Example notebooks\n"
+    lines += (len(lines) - 1) * "-" + "\n\n"
+    lines += (
+        "The Jupyter Notebooks used to create the input files and figures for \n"
+        + "each of the MODFLOW 6 `examples <examples.html>`_.\n\n"
+    )
+    f.write(lines)
+
+    lines = ".. nbgallery::\n"
+    lines += "    :name: Examples gallery\n\n"
+    for base_name in gwf_list:
+        lines += f"   _notebooks/{base_name}\n"
+    for base_name in gwt_list:
+        lines += f"   _notebooks/{base_name}\n"
+    lines += "\n\n"
+    f.write(lines)
 
 # -- Build the example restructured text files -------------------------------
 if not on_rtd:
@@ -76,7 +66,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "MODFLOW 6 Example Problems"
+project = "MODFLOW 6 Examples"
 copyright = "2020, MODFLOW 6 Development Team"
 author = "MODFLOW 6 Development Team"
 
@@ -99,8 +89,7 @@
     "IPython.sphinxext.ipython_console_highlighting",  # lowercase didn't work
     "sphinx.ext.autosectionlabel",
     "nbsphinx",
-    "nbsphinx_link",
-    "recommonmark",
+    "myst_parser",
     "sphinx_markdown_tables",
 ]
 
@@ -165,18 +154,18 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = [
+    'custom.css',
+    'theme_overrides.css'
+]
+
 html_context = {
     "github_repo": "https://github.com/MODFLOW-USGS/modflow6-examples",  # assuming an exact match
-    "github_version": "master",
     "display_github": False,
     "github_user": "modflow6-examples",
     "github_repo": "modflow6-examples",
     "github_version": "master",
     "doc_path": ".doc",
-    "css_files": [
-        "_static/theme_overrides.css",  # override wide tables in RTD theme
-        "_static/custom.css",
-    ],
 }
 
 numfig = True
@@ -194,17 +183,16 @@
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 html_short_title = "modflow6-examples"
-# html_favicon = ".._images/flopylogo.png"
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 html_use_smartypants = True
 
 # If false, no module index is generated.
-html_domain_indices = True
+html_domain_indices = False
 
 # If false, no index is generated.
-html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 html_split_index = False
@@ -220,3 +208,42 @@
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "mf6exdoc"
+
+# disable automatic notebook execution (built in CI for now)
+nbsphinx_execute = "never"
+
+nbsphinx_prolog = (
+    r"""
+{% set docname = env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+      This page was generated from
+      <a class="reference external" href="https://github.com/MODFLOW-USGS/modflow6-examples/blob/"""
+    + ref
+    + r"""/scripts/{{ env.docname.split('/')|last|e + '.py' }}">{{ env.docname.split('/')|last|e + '.py' }}</a>.
+      It's also available as a <a href="{{ env.docname.split('/')|last|e + '.ipynb' }}" class="reference download internal" download>notebook</a>.
+      <script>
+        if (document.location.host) {
+          let nbviewer_link = document.createElement('a');
+          nbviewer_link.setAttribute('href',
+            'https://nbviewer.org/url' +
+            (window.location.protocol == 'https:' ? 's/' : '/') +
+            window.location.host +
+            window.location.pathname.slice(0, -4) +
+            'ipynb');
+          nbviewer_link.innerHTML = 'View in <em>nbviewer</em>';
+          nbviewer_link.innerHTML = 'Or view it on <em>nbviewer</em>';
+          nbviewer_link.classList.add('reference');
+          nbviewer_link.classList.add('external');
+          document.currentScript.replaceWith(nbviewer_link, '.');
+        }
+      </script>
+    </div>
+"""
+)
+
+# Import Matplotlib to avoid this message in notebooks:
+# "Matplotlib is building the font cache; this may take a moment."
+import matplotlib.pyplot
diff --git a/.doc/examples.rst b/.doc/examples.rst
@@ -1,6 +1,6 @@
-============================
-MODFLOW 6 – Example problems
-============================
+====================
+Example descriptions
+====================
 
 
 .. toctree::
@@ -37,6 +37,9 @@ MODFLOW 6 – Example problems
    _examples/ex-gwf-drn-p01.rst
    _examples/ex-gwf-sagehen.rst
    _examples/ex-gwf-capture.rst
+   _examples/ex-gwf-radial.rst
+   _examples/ex-gwf-curvilinear-90.rst
+   _examples/ex-gwf-curvilinear.rst
    _examples/ex-gwt-keating.rst
    _examples/ex-gwt-moc3d-p01.rst
    _examples/ex-gwt-moc3d-p02.rst
@@ -62,3 +65,4 @@ MODFLOW 6 – Example problems
    _examples/ex-gwt-rotate.rst
    _examples/ex-gwt-hecht-mendez.rst
    _examples/ex-gwt-stallman.rst
+   _examples/ex-gwt-synthetic-valley.rst
diff --git a/.doc/index.rst b/.doc/index.rst
@@ -1,11 +1,12 @@
-.. MODFLOW 6 Example Problems documentation master file, created by
-   sphinx-quickstart on Tue Aug 25 14:58:45 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-MODFLOW 6 Example Problems
+MODFLOW 6 Examples
 ======================================================
 
+This site demonstrates MODFLOW 6 by constructing, running, post-processing and visualizing example scenarios with `FloPy <https://flopy.readthedocs.io>`_. Documentation is generated with Sphinx from the `MODFLOW 6 examples repository <https://github.com/MODFLOW-USGS/modflow6-examples>`_.
+
+For each example, this site includes a detailed description containing background information, explication of the modeling scenario, and any relevant citations, as well as a notebook containing the example's Python source code.
+
+Contents:
+
 .. toctree::
    :maxdepth: 1
 

diff --git a/.doc/introduction.md b/.doc/introduction.md
@@ -1,6 +1,6 @@
 ### Introduction
 
-This document describes example problems for MODFLOW 6. The examples demonstrate use of the capabilities for select components of MODFLOW 6. A pdf of the examples can be downloaded from [ReadtheDocs](https://modflow6-examples.readthedocs.io/en/latest/) or from the [current release](https://github.com/MODFLOW-USGS/modflow6-examples/releases/download/current/mf6examples.pdf) on [GitHub](https://github.com/MODFLOW-USGS/modflow6-examples/).
+MODFLOW 6 examples demonstrate the capabilities of select components of MODFLOW 6. A PDF document can be downloaded from [ReadtheDocs](https://modflow6-examples.readthedocs.io/en/latest/) or from the [current release](https://github.com/MODFLOW-USGS/modflow6-examples/releases/download/current/mf6examples.pdf) on [GitHub](https://github.com/MODFLOW-USGS/modflow6-examples/).
 
 Examples have been included for the MODFLOW 6 components summarized in the tables below.
 

diff --git a/.doc/notebook_examples.rst b/.doc/notebook_examples.rst
@@ -1,66 +1,70 @@
-MODFLOW 6 Examples - Jupyter Notebooks
---------------------------------------
+Example notebooks
+-----------------
 
 The Jupyter Notebooks used to create the input files and figures for 
 each of the MODFLOW 6 `examples <examples.html>`_.
 
-.. toctree::
-   :numbered:
-   :maxdepth: 1
+.. nbgallery::
+    :name: Examples gallery
 
-   ex-gwf-twri <_notebooks/ex-gwf-twri.ipynb>
-   ex-gwf-bcf2ss <_notebooks/ex-gwf-bcf2ss.ipynb>
-   ex-gwf-advtidal <_notebooks/ex-gwf-advtidal.ipynb>
-   ex-gwf-fhb <_notebooks/ex-gwf-fhb.ipynb>
-   ex-gwf-u1disv <_notebooks/ex-gwf-u1disv.ipynb>
-   ex-gwf-u1gwfgwf <_notebooks/ex-gwf-u1gwfgwf.ipynb>
-   ex-gwf-nwt-p02 <_notebooks/ex-gwf-nwt-p02.ipynb>
-   ex-gwf-nwt-p03 <_notebooks/ex-gwf-nwt-p03.ipynb>
-   ex-gwf-zaidel <_notebooks/ex-gwf-zaidel.ipynb>
-   ex-gwf-sfr-p01 <_notebooks/ex-gwf-sfr-p01.ipynb>
-   ex-gwf-sfr-p01b <_notebooks/ex-gwf-sfr-p01b.ipynb>
-   ex-gwf-lak-p01 <_notebooks/ex-gwf-lak-p01.ipynb>
-   ex-gwf-lak-p02 <_notebooks/ex-gwf-lak-p02.ipynb>
-   ex-gwf-maw-p01 <_notebooks/ex-gwf-maw-p01.ipynb>
-   ex-gwf-maw-p02 <_notebooks/ex-gwf-maw-p02.ipynb>
-   ex-gwf-maw-p03 <_notebooks/ex-gwf-maw-p03.ipynb>
-   ex-gwf-bump <_notebooks/ex-gwf-bump.ipynb>
-   ex-gwf-disvmesh <_notebooks/ex-gwf-disvmesh.ipynb>
-   ex-gwf-hani <_notebooks/ex-gwf-hani.ipynb>
-   ex-gwf-whirl <_notebooks/ex-gwf-whirl.ipynb>
-   ex-gwf-lgr <_notebooks/ex-gwf-lgr.ipynb>
-   ex-gwf-lgrv <_notebooks/ex-gwf-lgrv.ipynb>
-   ex-gwf-spbc <_notebooks/ex-gwf-spbc.ipynb>
-   ex-gwf-csub-p01 <_notebooks/ex-gwf-csub-p01.ipynb>
-   ex-gwf-csub-p02 <_notebooks/ex-gwf-csub-p02.ipynb>
-   ex-gwf-csub-p03 <_notebooks/ex-gwf-csub-p03.ipynb>
-   ex-gwf-csub-p04 <_notebooks/ex-gwf-csub-p04.ipynb>
-   ex-gwf-drn-p01 <_notebooks/ex-gwf-drn-p01.ipynb>
-   ex-gwf-sagehen <_notebooks/ex-gwf-sagehen.ipynb>
-   ex-gwf-capture <_notebooks/ex-gwf-capture.ipynb>
-   ex-gwt-keating <_notebooks/ex-gwt-keating.ipynb>
-   ex-gwt-moc3d-p01 <_notebooks/ex-gwt-moc3d-p01.ipynb>
-   ex-gwt-moc3d-p02 <_notebooks/ex-gwt-moc3d-p02.ipynb>
-   ex-gwt-moc3d-p02tg <_notebooks/ex-gwt-moc3d-p02tg.ipynb>
-   ex-gwt-mt3dms-p01 <_notebooks/ex-gwt-mt3dms-p01.ipynb>
-   ex-gwt-mt3dms-p02 <_notebooks/ex-gwt-mt3dms-p02.ipynb>
-   ex-gwt-mt3dms-p03 <_notebooks/ex-gwt-mt3dms-p03.ipynb>
-   ex-gwt-mt3dms-p04 <_notebooks/ex-gwt-mt3dms-p04.ipynb>
-   ex-gwt-mt3dms-p05 <_notebooks/ex-gwt-mt3dms-p05.ipynb>
-   ex-gwt-mt3dms-p06 <_notebooks/ex-gwt-mt3dms-p06.ipynb>
-   ex-gwt-mt3dms-p07 <_notebooks/ex-gwt-mt3dms-p07.ipynb>
-   ex-gwt-mt3dms-p08 <_notebooks/ex-gwt-mt3dms-p08.ipynb>
-   ex-gwt-mt3dms-p09 <_notebooks/ex-gwt-mt3dms-p09.ipynb>
-   ex-gwt-mt3dms-p10 <_notebooks/ex-gwt-mt3dms-p10.ipynb>
-   ex-gwt-gwtgwt-p10 <_notebooks/ex-gwt-gwtgwt-p10.ipynb>
-   ex-gwt-mt3dsupp631 <_notebooks/ex-gwt-mt3dsupp631.ipynb>
-   ex-gwt-mt3dsupp632 <_notebooks/ex-gwt-mt3dsupp632.ipynb>
-   ex-gwt-mt3dsupp82 <_notebooks/ex-gwt-mt3dsupp82.ipynb>
-   ex-gwt-prudic2004t2 <_notebooks/ex-gwt-prudic2004t2.ipynb>
-   ex-gwt-uzt-2d <_notebooks/ex-gwt-uzt-2d.ipynb>
-   ex-gwt-henry <_notebooks/ex-gwt-henry.ipynb>
-   ex-gwt-saltlake <_notebooks/ex-gwt-saltlake.ipynb>
-   ex-gwt-rotate <_notebooks/ex-gwt-rotate.ipynb>
-   ex-gwt-hecht-mendez <_notebooks/ex-gwt-hecht-mendez.ipynb>
+   _notebooks/ex-gwf-twri
+   _notebooks/ex-gwf-bcf2ss
+   _notebooks/ex-gwf-advtidal
+   _notebooks/ex-gwf-fhb
+   _notebooks/ex-gwf-u1disv
+   _notebooks/ex-gwf-u1gwfgwf
+   _notebooks/ex-gwf-nwt-p02
+   _notebooks/ex-gwf-nwt-p03
+   _notebooks/ex-gwf-zaidel
+   _notebooks/ex-gwf-sfr-p01
+   _notebooks/ex-gwf-sfr-p01b
+   _notebooks/ex-gwf-lak-p01
+   _notebooks/ex-gwf-lak-p02
+   _notebooks/ex-gwf-maw-p01
+   _notebooks/ex-gwf-maw-p02
+   _notebooks/ex-gwf-maw-p03
+   _notebooks/ex-gwf-bump
+   _notebooks/ex-gwf-disvmesh
+   _notebooks/ex-gwf-hani
+   _notebooks/ex-gwf-whirl
+   _notebooks/ex-gwf-lgr
+   _notebooks/ex-gwf-lgrv
+   _notebooks/ex-gwf-spbc
+   _notebooks/ex-gwf-csub-p01
+   _notebooks/ex-gwf-csub-p02
+   _notebooks/ex-gwf-csub-p03
+   _notebooks/ex-gwf-csub-p04
+   _notebooks/ex-gwf-drn-p01
+   _notebooks/ex-gwf-sagehen
+   _notebooks/ex-gwf-capture
+   _notebooks/ex-gwf-radial
+   _notebooks/ex-gwf-curvilinear-90
+   _notebooks/ex-gwf-curvilinear
+   _notebooks/ex-gwt-keating
+   _notebooks/ex-gwt-moc3d-p01
+   _notebooks/ex-gwt-moc3d-p02
+   _notebooks/ex-gwt-moc3d-p02tg
+   _notebooks/ex-gwt-mt3dms-p01
+   _notebooks/ex-gwt-mt3dms-p02
+   _notebooks/ex-gwt-mt3dms-p03
+   _notebooks/ex-gwt-mt3dms-p04
+   _notebooks/ex-gwt-mt3dms-p05
+   _notebooks/ex-gwt-mt3dms-p06
+   _notebooks/ex-gwt-mt3dms-p07
+   _notebooks/ex-gwt-mt3dms-p08
+   _notebooks/ex-gwt-mt3dms-p09
+   _notebooks/ex-gwt-mt3dms-p10
+   _notebooks/ex-gwt-gwtgwt-p10
+   _notebooks/ex-gwt-mt3dsupp631
+   _notebooks/ex-gwt-mt3dsupp632
+   _notebooks/ex-gwt-mt3dsupp82
+   _notebooks/ex-gwt-prudic2004t2
+   _notebooks/ex-gwt-uzt-2d
+   _notebooks/ex-gwt-henry
+   _notebooks/ex-gwt-saltlake
+   _notebooks/ex-gwt-rotate
+   _notebooks/ex-gwt-hecht-mendez
+   _notebooks/ex-gwt-stallman
+   _notebooks/ex-gwt-synthetic-valley
 
 
diff --git a/.doc/requirements.rtd.txt b/.doc/requirements.rtd.txt
@@ -2,8 +2,8 @@ nbsphinx
 nbsphinx_link
 ipython
 ipykernel
-recommonmark
 rtds_action
 sphinx_markdown_tables
 sphinx-rtd-theme
 pygments>=2.4.1
+myst-parser