Skip to content

Commit 011aeba

Browse files
wpbonelliwpbonelli
authored
docs(rtd): various enhancements (#138)
* use myst-parser * update examples.rst * fix CSS config in conf.py * fix render order for descriptions and notebooks on RTD * update DEVELOPER.md (mention Pooch) * add download links to rendered notebooks * convert notebook list to nbsphinx gallery * language tweaks: problem -> scenario * expand explication on splash pages
1 parent 86f7cb5 commit 011aeba

10 files changed

+310
-293
lines changed

‎.doc/conf.py

+70-36
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,13 @@
1212
#
1313
import os
1414
import re
15+
from modflow_devtools.misc import get_env
1516

1617
# -- set boolean indicating if running on readthedocs server -----------------
17-
on_rtd = os.environ.get("READTHEDOCS") == "True"
18+
on_rtd = get_env("READTHEDOCS", False)
19+
20+
# -- get git ref from which we are building the docs -------------------------
21+
ref = get_env("READTHEDOCS_GIT_IDENTIFIER", "master")
1822

1923
# -- setup regular expression for body.tex -----------------------------------
2024
ex_regex = re.compile("\\\\input{sections/(.*?)\\}")
@@ -32,31 +36,23 @@
3236
gwt_list.append(v.replace(".tex", ""))
3337

3438
# -- Build examples.rst for notebooks to .doc --------------------------------
35-
f = open("notebook_examples.rst", "w")
36-
37-
lines = "MODFLOW 6 Examples - Jupyter Notebooks\n"
38-
lines += (len(lines) - 1) * "-" + "\n\n"
39-
lines += (
40-
"The Jupyter Notebooks used to create the input files and figures for \n"
41-
+ "each of the MODFLOW 6 `examples <examples.html>`_.\n\n"
42-
)
43-
f.write(lines)
44-
45-
# gwf examples Jupyter Notebooks
46-
lines = ".. toctree::\n"
47-
lines += " :numbered:\n"
48-
lines += " :maxdepth: 1\n\n"
49-
for base_name in gwf_list:
50-
lines += f" {base_name} "
51-
lines += "<{}>\n".format(os.path.join("_notebooks", base_name + ".ipynb"))
52-
for base_name in gwt_list:
53-
lines += f" {base_name} "
54-
lines += "<{}>\n".format(os.path.join("_notebooks", base_name + ".ipynb"))
55-
lines += "\n\n"
56-
f.write(lines)
57-
58-
# close the restructured text file
59-
f.close()
39+
with open("notebook_examples.rst", "w") as f:
40+
lines = "Example notebooks\n"
41+
lines += (len(lines) - 1) * "-" + "\n\n"
42+
lines += (
43+
"The Jupyter Notebooks used to create the input files and figures for \n"
44+
+ "each of the MODFLOW 6 `examples <examples.html>`_.\n\n"
45+
)
46+
f.write(lines)
47+
48+
lines = ".. nbgallery::\n"
49+
lines += " :name: Examples gallery\n\n"
50+
for base_name in gwf_list:
51+
lines += f" _notebooks/{base_name}\n"
52+
for base_name in gwt_list:
53+
lines += f" _notebooks/{base_name}\n"
54+
lines += "\n\n"
55+
f.write(lines)
6056

6157
# -- Build the example restructured text files -------------------------------
6258
if not on_rtd:
@@ -70,7 +66,7 @@
7066

7167
# -- Project information -----------------------------------------------------
7268

73-
project = "MODFLOW 6 Example Problems"
69+
project = "MODFLOW 6 Examples"
7470
copyright = "2020, MODFLOW 6 Development Team"
7571
author = "MODFLOW 6 Development Team"
7672

@@ -93,8 +89,7 @@
9389
"IPython.sphinxext.ipython_console_highlighting", # lowercase didn't work
9490
"sphinx.ext.autosectionlabel",
9591
"nbsphinx",
96-
"nbsphinx_link",
97-
"recommonmark",
92+
"myst_parser",
9893
"sphinx_markdown_tables",
9994
]
10095

@@ -159,6 +154,11 @@
159154
# so a file named "default.css" will overwrite the builtin "default.css".
160155
html_static_path = ["_static"]
161156

157+
html_css_files = [
158+
'custom.css',
159+
'theme_overrides.css'
160+
]
161+
162162
html_context = {
163163
"github_repo": "https://github.com/MODFLOW-USGS/modflow6-examples", # assuming an exact match
164164
"github_version": "master",
@@ -167,10 +167,6 @@
167167
"github_repo": "modflow6-examples",
168168
"github_version": "master",
169169
"doc_path": ".doc",
170-
"css_files": [
171-
"_static/theme_overrides.css", # override wide tables in RTD theme
172-
"_static/custom.css",
173-
],
174170
}
175171

176172
numfig = True
@@ -188,17 +184,16 @@
188184

189185
# A shorter title for the navigation bar. Default is the same as html_title.
190186
html_short_title = "modflow6-examples"
191-
# html_favicon = ".._images/flopylogo.png"
192187

193188
# If true, SmartyPants will be used to convert quotes and dashes to
194189
# typographically correct entities.
195190
html_use_smartypants = True
196191

197192
# If false, no module index is generated.
198-
html_domain_indices = True
193+
html_domain_indices = False
199194

200195
# If false, no index is generated.
201-
html_use_index = True
196+
html_use_index = False
202197

203198
# If true, the index is split into individual pages for each letter.
204199
html_split_index = False
@@ -214,3 +209,42 @@
214209

215210
# Output file base name for HTML help builder.
216211
htmlhelp_basename = "mf6exdoc"
212+
213+
# disable automatic notebook execution (nbs are built in CI for now)
214+
nbsphinx_execute = "never"
215+
216+
nbsphinx_prolog = (
217+
r"""
218+
{% set docname = env.doc2path(env.docname, base=None) %}
219+
220+
.. raw:: html
221+
222+
<div class="admonition note">
223+
This page was generated from
224+
<a class="reference external" href="https://github.com/MODFLOW-USGS/modflow6-examples/blob/"""
225+
+ ref
226+
+ r"""/scripts/{{ env.docname.split('/')|last|e + '.py' }}">{{ env.docname.split('/')|last|e + '.py' }}</a>.
227+
It's also available as a <a href="{{ env.docname.split('/')|last|e + '.ipynb' }}" class="reference download internal" download>notebook</a>.
228+
<script>
229+
if (document.location.host) {
230+
let nbviewer_link = document.createElement('a');
231+
nbviewer_link.setAttribute('href',
232+
'https://nbviewer.org/url' +
233+
(window.location.protocol == 'https:' ? 's/' : '/') +
234+
window.location.host +
235+
window.location.pathname.slice(0, -4) +
236+
'ipynb');
237+
nbviewer_link.innerHTML = 'View in <em>nbviewer</em>';
238+
nbviewer_link.innerHTML = 'Or view it on <em>nbviewer</em>';
239+
nbviewer_link.classList.add('reference');
240+
nbviewer_link.classList.add('external');
241+
document.currentScript.replaceWith(nbviewer_link, '.');
242+
}
243+
</script>
244+
</div>
245+
"""
246+
)
247+
248+
# Import Matplotlib to avoid this message in notebooks:
249+
# "Matplotlib is building the font cache; this may take a moment."
250+
import matplotlib.pyplot

‎.doc/examples.rst

+7-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
============================
2-
MODFLOW 6 – Example problems
3-
============================
1+
====================
2+
Example descriptions
3+
====================
44

55

66
.. toctree::
@@ -37,6 +37,9 @@ MODFLOW 6 – Example problems
3737
_examples/ex-gwf-drn-p01.rst
3838
_examples/ex-gwf-sagehen.rst
3939
_examples/ex-gwf-capture.rst
40+
_examples/ex-gwf-radial.rst
41+
_examples/ex-gwf-curvilinear-90.rst
42+
_examples/ex-gwf-curvilinear.rst
4043
_examples/ex-gwt-keating.rst
4144
_examples/ex-gwt-moc3d-p01.rst
4245
_examples/ex-gwt-moc3d-p02.rst
@@ -62,3 +65,4 @@ MODFLOW 6 – Example problems
6265
_examples/ex-gwt-rotate.rst
6366
_examples/ex-gwt-hecht-mendez.rst
6467
_examples/ex-gwt-stallman.rst
68+
_examples/ex-gwt-synthetic-valley.rst

‎.doc/index.rst

+7-6
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
1-
.. MODFLOW 6 Example Problems documentation master file, created by
2-
sphinx-quickstart on Tue Aug 25 14:58:45 2020.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
5-
6-
MODFLOW 6 Example Problems
1+
MODFLOW 6 Examples
72
======================================================
83

4+
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>`_.
5+
6+
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.
7+
8+
Contents:
9+
910
.. toctree::
1011
:maxdepth: 1
1112

‎.doc/introduction.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
### Introduction
22

3-
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/).
3+
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/).
44

55
Examples have been included for the MODFLOW 6 components summarized in the tables below.
66

‎.doc/notebook_examples.rst

+63-59
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,70 @@
1-
MODFLOW 6 Examples - Jupyter Notebooks
2-
--------------------------------------
1+
Example notebooks
2+
-----------------
33

44
The Jupyter Notebooks used to create the input files and figures for
55
each of the MODFLOW 6 `examples <examples.html>`_.
66

7-
.. toctree::
8-
:numbered:
9-
:maxdepth: 1
7+
.. nbgallery::
8+
:name: Examples gallery
109

11-
ex-gwf-twri <_notebooks/ex-gwf-twri.ipynb>
12-
ex-gwf-bcf2ss <_notebooks/ex-gwf-bcf2ss.ipynb>
13-
ex-gwf-advtidal <_notebooks/ex-gwf-advtidal.ipynb>
14-
ex-gwf-fhb <_notebooks/ex-gwf-fhb.ipynb>
15-
ex-gwf-u1disv <_notebooks/ex-gwf-u1disv.ipynb>
16-
ex-gwf-u1gwfgwf <_notebooks/ex-gwf-u1gwfgwf.ipynb>
17-
ex-gwf-nwt-p02 <_notebooks/ex-gwf-nwt-p02.ipynb>
18-
ex-gwf-nwt-p03 <_notebooks/ex-gwf-nwt-p03.ipynb>
19-
ex-gwf-zaidel <_notebooks/ex-gwf-zaidel.ipynb>
20-
ex-gwf-sfr-p01 <_notebooks/ex-gwf-sfr-p01.ipynb>
21-
ex-gwf-sfr-p01b <_notebooks/ex-gwf-sfr-p01b.ipynb>
22-
ex-gwf-lak-p01 <_notebooks/ex-gwf-lak-p01.ipynb>
23-
ex-gwf-lak-p02 <_notebooks/ex-gwf-lak-p02.ipynb>
24-
ex-gwf-maw-p01 <_notebooks/ex-gwf-maw-p01.ipynb>
25-
ex-gwf-maw-p02 <_notebooks/ex-gwf-maw-p02.ipynb>
26-
ex-gwf-maw-p03 <_notebooks/ex-gwf-maw-p03.ipynb>
27-
ex-gwf-bump <_notebooks/ex-gwf-bump.ipynb>
28-
ex-gwf-disvmesh <_notebooks/ex-gwf-disvmesh.ipynb>
29-
ex-gwf-hani <_notebooks/ex-gwf-hani.ipynb>
30-
ex-gwf-whirl <_notebooks/ex-gwf-whirl.ipynb>
31-
ex-gwf-lgr <_notebooks/ex-gwf-lgr.ipynb>
32-
ex-gwf-lgrv <_notebooks/ex-gwf-lgrv.ipynb>
33-
ex-gwf-spbc <_notebooks/ex-gwf-spbc.ipynb>
34-
ex-gwf-csub-p01 <_notebooks/ex-gwf-csub-p01.ipynb>
35-
ex-gwf-csub-p02 <_notebooks/ex-gwf-csub-p02.ipynb>
36-
ex-gwf-csub-p03 <_notebooks/ex-gwf-csub-p03.ipynb>
37-
ex-gwf-csub-p04 <_notebooks/ex-gwf-csub-p04.ipynb>
38-
ex-gwf-drn-p01 <_notebooks/ex-gwf-drn-p01.ipynb>
39-
ex-gwf-sagehen <_notebooks/ex-gwf-sagehen.ipynb>
40-
ex-gwf-capture <_notebooks/ex-gwf-capture.ipynb>
41-
ex-gwt-keating <_notebooks/ex-gwt-keating.ipynb>
42-
ex-gwt-moc3d-p01 <_notebooks/ex-gwt-moc3d-p01.ipynb>
43-
ex-gwt-moc3d-p02 <_notebooks/ex-gwt-moc3d-p02.ipynb>
44-
ex-gwt-moc3d-p02tg <_notebooks/ex-gwt-moc3d-p02tg.ipynb>
45-
ex-gwt-mt3dms-p01 <_notebooks/ex-gwt-mt3dms-p01.ipynb>
46-
ex-gwt-mt3dms-p02 <_notebooks/ex-gwt-mt3dms-p02.ipynb>
47-
ex-gwt-mt3dms-p03 <_notebooks/ex-gwt-mt3dms-p03.ipynb>
48-
ex-gwt-mt3dms-p04 <_notebooks/ex-gwt-mt3dms-p04.ipynb>
49-
ex-gwt-mt3dms-p05 <_notebooks/ex-gwt-mt3dms-p05.ipynb>
50-
ex-gwt-mt3dms-p06 <_notebooks/ex-gwt-mt3dms-p06.ipynb>
51-
ex-gwt-mt3dms-p07 <_notebooks/ex-gwt-mt3dms-p07.ipynb>
52-
ex-gwt-mt3dms-p08 <_notebooks/ex-gwt-mt3dms-p08.ipynb>
53-
ex-gwt-mt3dms-p09 <_notebooks/ex-gwt-mt3dms-p09.ipynb>
54-
ex-gwt-mt3dms-p10 <_notebooks/ex-gwt-mt3dms-p10.ipynb>
55-
ex-gwt-gwtgwt-p10 <_notebooks/ex-gwt-gwtgwt-p10.ipynb>
56-
ex-gwt-mt3dsupp631 <_notebooks/ex-gwt-mt3dsupp631.ipynb>
57-
ex-gwt-mt3dsupp632 <_notebooks/ex-gwt-mt3dsupp632.ipynb>
58-
ex-gwt-mt3dsupp82 <_notebooks/ex-gwt-mt3dsupp82.ipynb>
59-
ex-gwt-prudic2004t2 <_notebooks/ex-gwt-prudic2004t2.ipynb>
60-
ex-gwt-uzt-2d <_notebooks/ex-gwt-uzt-2d.ipynb>
61-
ex-gwt-henry <_notebooks/ex-gwt-henry.ipynb>
62-
ex-gwt-saltlake <_notebooks/ex-gwt-saltlake.ipynb>
63-
ex-gwt-rotate <_notebooks/ex-gwt-rotate.ipynb>
64-
ex-gwt-hecht-mendez <_notebooks/ex-gwt-hecht-mendez.ipynb>
10+
_notebooks/ex-gwf-twri
11+
_notebooks/ex-gwf-bcf2ss
12+
_notebooks/ex-gwf-advtidal
13+
_notebooks/ex-gwf-fhb
14+
_notebooks/ex-gwf-u1disv
15+
_notebooks/ex-gwf-u1gwfgwf
16+
_notebooks/ex-gwf-nwt-p02
17+
_notebooks/ex-gwf-nwt-p03
18+
_notebooks/ex-gwf-zaidel
19+
_notebooks/ex-gwf-sfr-p01
20+
_notebooks/ex-gwf-sfr-p01b
21+
_notebooks/ex-gwf-lak-p01
22+
_notebooks/ex-gwf-lak-p02
23+
_notebooks/ex-gwf-maw-p01
24+
_notebooks/ex-gwf-maw-p02
25+
_notebooks/ex-gwf-maw-p03
26+
_notebooks/ex-gwf-bump
27+
_notebooks/ex-gwf-disvmesh
28+
_notebooks/ex-gwf-hani
29+
_notebooks/ex-gwf-whirl
30+
_notebooks/ex-gwf-lgr
31+
_notebooks/ex-gwf-lgrv
32+
_notebooks/ex-gwf-spbc
33+
_notebooks/ex-gwf-csub-p01
34+
_notebooks/ex-gwf-csub-p02
35+
_notebooks/ex-gwf-csub-p03
36+
_notebooks/ex-gwf-csub-p04
37+
_notebooks/ex-gwf-drn-p01
38+
_notebooks/ex-gwf-sagehen
39+
_notebooks/ex-gwf-capture
40+
_notebooks/ex-gwf-radial
41+
_notebooks/ex-gwf-curvilinear-90
42+
_notebooks/ex-gwf-curvilinear
43+
_notebooks/ex-gwt-keating
44+
_notebooks/ex-gwt-moc3d-p01
45+
_notebooks/ex-gwt-moc3d-p02
46+
_notebooks/ex-gwt-moc3d-p02tg
47+
_notebooks/ex-gwt-mt3dms-p01
48+
_notebooks/ex-gwt-mt3dms-p02
49+
_notebooks/ex-gwt-mt3dms-p03
50+
_notebooks/ex-gwt-mt3dms-p04
51+
_notebooks/ex-gwt-mt3dms-p05
52+
_notebooks/ex-gwt-mt3dms-p06
53+
_notebooks/ex-gwt-mt3dms-p07
54+
_notebooks/ex-gwt-mt3dms-p08
55+
_notebooks/ex-gwt-mt3dms-p09
56+
_notebooks/ex-gwt-mt3dms-p10
57+
_notebooks/ex-gwt-gwtgwt-p10
58+
_notebooks/ex-gwt-mt3dsupp631
59+
_notebooks/ex-gwt-mt3dsupp632
60+
_notebooks/ex-gwt-mt3dsupp82
61+
_notebooks/ex-gwt-prudic2004t2
62+
_notebooks/ex-gwt-uzt-2d
63+
_notebooks/ex-gwt-henry
64+
_notebooks/ex-gwt-saltlake
65+
_notebooks/ex-gwt-rotate
66+
_notebooks/ex-gwt-hecht-mendez
67+
_notebooks/ex-gwt-stallman
68+
_notebooks/ex-gwt-synthetic-valley
6569

6670

‎.doc/requirements.rtd.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ nbsphinx
22
nbsphinx_link
33
ipython
44
ipykernel
5-
recommonmark
65
rtds_action
76
sphinx_markdown_tables
87
sphinx-rtd-theme
98
pygments>=2.4.1
9+
myst-parser

‎DEVELOPER.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ This document describes development procedures and conventions for the MODFLOW 6
2323

2424
The example models in this repository are composed with FloPy in the Python files under `scripts/`. Notebooks are generated from these with [`jupytext`](https://github.com/mwouts/jupytext) for the [online documentation](https://modflow6-examples.readthedocs.io/en/stable/) and/or for use with `jupyter`. A small volume of supporting data live in files under `data/`.
2525

26+
**Note:** example scripts do not access the `data/` folder directly &mdash; rather, on first run, they download and cache files from GitHub with a tool called [Pooch](https://www.fatiando.org/pooch/latest/). This allows running scripts and/or notebooks downloaded from the [documentation site](https://modflow6-examples.readthedocs.io/en/stable/) without first cloning the repository and/or manually downloading data files.
27+
2628
Scripts may contain one or more example scenarios. Each script creates one or more subdirectories of `examples/` to use as a workspace, one per example scenario. Internally, the scripts are structured similarly, proceeding through the following steps:
2729

2830
1. Define & build models
@@ -39,7 +41,7 @@ The scripts parse environment variables to control several behaviors, all of whi
3941
- `PLOT_SAVE`: whether to save static plots to `figures/`
4042
- `GIF`: whether to save GIFs to `figures/` (only relevant for a small subset of scripts)
4143

42-
If variables are not found when a script is run directly, behaviors are enabled by default. When scripts are run via `pytest`, by default plots are not shown (to avoid the need to manually close plot widgets).
44+
If variables are not found when a script is run directly, behaviors are enabled by default. When scripts are run via `pytest`, by default plots are not shown (to avoid the need to manually close plot widgets). Pytest CLI flags can be used to control each switch &mdash; see below for details.
4345

4446
## Prerequisites
4547

0 commit comments

Comments
 (0)