ci(release): fix nightly build (MODFLOW-USGS#1965)

* The nightly build is failing at the build docs step for lack of a deprecations table, which we stopped versioning and began generating automatically in docs: don't version files generated from DFNs MODFLOW-USGS#1946. Make the table before building PDF documents in the release workflow, and in .build_rtd_docs/conf.py (needed for RTD).

* Be lenient about the name of the zip file asset we try to download from the examples repo as this changed in modflow6-examples#217. This also tripped up the nightly build.

* Remove the prog argument to argparse.ArgumentParser in all the distribution scripts, I thought this was supposed to be a text description of the program but it is the command itself. This fixes the first line of output of <script> -h.

* Miscellaneous fixes and cleanup in the distribution scripts

.build_rtd_docs/conf.py

@@ -81,6 +81,18 @@
 dst = os.path.join(dstdir, fpth)
 shutil.copy(src, dst)
 
+# -- build the deprecations table --------------------------------------------
+print("Build the deprecations markdown table")
+pth = os.path.join("..", "doc", "mf6io", "mf6ivar")
+args = (sys.executable, "deprecations.py")
+# run the command
+proc = Popen(args, stdout=PIPE, stderr=PIPE, cwd=pth)
+stdout, stderr = proc.communicate()
+if stdout:
+    print(stdout.decode("utf-8"))
+if stderr:
+    print("Errors:\n{}".format(stderr.decode("utf-8")))
+
 # -- copy deprecations markdown ---------------------------------------------
 print("Copy the deprecations table")
 dstdir = "_mf6run"

.github/workflows/release.yml

@@ -459,6 +459,10 @@ jobs:
           name: deprecations
           path: modflow6/doc/mf6io/mf6ivar/md/deprecations.md
 
+      - name: Build MF6IO files from DFNs
+        working-directory: modflow6/doc/mf6io/mf6ivar
+        run: python mf6ivar.py
+
       - name: Build documentation
         env:
           # this step is lazy about building the mf6 examples PDF document, first

distribution/benchmark.py

@@ -428,11 +428,10 @@ def test_run_benchmarks(tmp_path):
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(
-        prog="Benchmark MODFLOW 6 versions on example models",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=textwrap.dedent(
             """\
-            Benchmarks the current version of MODFLOW 6 against the latest official release.
+            Benchmarks the current version of MODFLOW 6 against the latest official release,
             with the example models stored in the MODFLOW-USGS/modflow6-examples repository.
             """
         ),

distribution/build_dist.py

@@ -111,16 +111,21 @@ def test_copy_sources(tmp_path):
 def setup_examples(
     bin_path: PathLike,
     examples_path: PathLike,
-    overwrite: bool = False,
+    force: bool = False,
     models: Optional[List[str]] = None,
 ):
     examples_path = Path(examples_path).expanduser().absolute()
-    latest = get_release("MODFLOW-USGS/modflow6-examples", "latest")
+
+    # find and download example models distribution from latest examples release
+    latest = get_release(
+        "MODFLOW-USGS/modflow6-examples", tag="latest", verbose=True
+    )
     assets = latest["assets"]
+    print(f"Found {len(assets)} assets from the latest examples release:")
+    pprint([a["name"] for a in assets])
     asset = next(
-        iter([a for a in assets if a["name"] == "mf6examples.zip"]), None
+        iter([a for a in assets if a["name"].endswith("examples.zip")]), None
     )
-    # download example models zip asset
     download_and_unzip(
         asset["browser_download_url"], examples_path, verbose=True
     )
@@ -141,7 +146,7 @@ def setup_examples(
     model_paths = get_model_paths(examples_path)
     for mp in model_paths:
         script_path = mp / f"run{SCR_EXT}"
-        if not overwrite and script_path.is_file():
+        if not force and script_path.is_file():
             print(f"Script {script_path} already exists")
         else:
             print(f"Creating {script_path}")
@@ -165,7 +170,7 @@ def setup_examples(
 
     # add runall.sh/bat, which runs all examples
     script_path = examples_path / f"runall{SCR_EXT}"
-    if not overwrite and script_path.is_file():
+    if not force and script_path.is_file():
         print(f"Script {script_path} already exists")
     else:
         print(f"Creating {script_path}")
@@ -191,7 +196,7 @@ def setup_examples(
 
 
 def build_programs_meson(
-    build_path: PathLike, bin_path: PathLike, overwrite: bool = False
+    build_path: PathLike, bin_path: PathLike, force: bool = False
 ):
     build_path = Path(build_path).expanduser().absolute()
     bin_path = Path(bin_path).expanduser().absolute()
@@ -204,7 +209,7 @@ def build_programs_meson(
     lib_paths = [bin_path / f"libmf6{LIB_EXT}"]
 
     if (
-        not overwrite
+        not force
         and all(p.is_file() for p in exe_paths)
         and all(p.is_file() for p in lib_paths)
     ):
@@ -293,7 +298,7 @@ def build_distribution(
     build_path: PathLike,
     output_path: PathLike,
     full: bool = False,
-    overwrite: bool = False,
+    force: bool = False,
     models: Optional[List[str]] = None,
 ):
     print(f"Building {'full' if full else 'minimal'} distribution")
@@ -305,7 +310,7 @@ def build_distribution(
     build_programs_meson(
         build_path=build_path,
         bin_path=output_path / "bin",
-        overwrite=overwrite,
+        force=force,
     )
 
     # code.json metadata
@@ -319,7 +324,7 @@ def build_distribution(
     setup_examples(
         bin_path=output_path / "bin",
         examples_path=output_path / "examples",
-        overwrite=overwrite,
+        force=force,
         models=models,
     )
 
@@ -334,7 +339,7 @@ def build_distribution(
         bin_path=output_path / "bin",
         full=full,
         output_path=output_path / "doc",
-        overwrite=overwrite,
+        force=force,
     )
 
 
@@ -348,7 +353,7 @@ def test_build_distribution(tmp_path, full):
         build_path=tmp_path / "builddir",
         output_path=output_path,
         full=full,
-        overwrite=True,
+        force=True,
     )
 
     if full:
@@ -378,16 +383,20 @@ def test_build_distribution(tmp_path, full):
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(
-        prog="Create a Modflow 6 distribution directory for release",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=textwrap.dedent(
             """\
-            Create a distribution folder. If no output path is provided
-            distribution files are written to the distribution/ folder.
+            Create a MODFLOW 6 distribution. If output path is provided
+            distribution files are written to the selected path, if not
+            they are written to the distribution/ project subdirectory.
             By default a minimal distribution containing only binaries,
             mf6io documentation, release notes and metadata (code.json)
             is created. To create a full distribution including sources
-            and examples, use the --full flag.
+            and examples, use the --full flag. Models to be included in
+            the examples and documentation can be selected with --model
+            (or -m), which may be used multiple times. Use --force (-f)
+            to overwrite preexisting distribution artifacts; by default
+            the script is lazy and will only create what it can't find.
             """
         ),
     )
@@ -436,6 +445,6 @@ def test_build_distribution(tmp_path, full):
         build_path=build_path,
         output_path=out_path,
         full=args.full,
-        overwrite=args.force,
+        force=args.force,
         models=models,
     )