chore(pixi): add pixi task to make release notes tex file, update dev docs (#2282)

#2108 neglected to document mk_releasenotes.py for developers, do so. Give the script named --toml and --tex parameters with default values develop.toml and develop.tex in the same directory as the script. Add a pixi task to run the script with defaults. Rename the deprecations task to collect-deprecations, following pattern verb[-noun].

Author: wpbonelli

.github/workflows/docs.yml

@@ -152,7 +152,7 @@ jobs:
 
       - name: Collect deprecations
         working-directory: modflow6
-        run: pixi run deprecations
+        run: pixi run collect-deprecations
 
       - name: Show deprecations
         working-directory: modflow6/doc/mf6io/mf6ivar/md

distribution/README.md

@@ -78,17 +78,17 @@ These should occur roughly in the order presented above. The procedure is automa
 
 ### Update release notes
 
-The release notes document is constructed from the `doc/ReleaseNotes/ReleaseNotes.tex` LaTeX file. During each development cycle, release notes should be maintained in `doc/ReleaseNotes/develop.tex` — this file is referenced from `doc/ReleaseNotes/ReleaseNotes.tex`.
+The release notes PDF document is constructed from the `doc/ReleaseNotes/ReleaseNotes.tex` LaTeX file. During development, release notes should be maintained in `doc/ReleaseNotes/develop.toml` — this file is turned into a LaTeX file by `doc/ReleaseNotes/mk_releasenotes.py`. A pixi task is available for this, e.g. `pixi run make-release-notes`. The resulting LaTex file is referenced from `doc/ReleaseNotes/ReleaseNotes.tex`.
 
 Before making a release, add a line to the Release History section of `ReleaseNotes.tex` providing the version number, date and DOI of the current release, e.g. `6.4.4 & February 13, 2024 & \url{https://doi.org/10.5066/P9FL1JCC}`.
 
 After each release is made, several steps are required to reset the release notes for the next development cycle:
 
 - copy `develop.tex` into a new file `doc/ReleaseNotes/previous/vx.y.z.tex` (where `x.y.z` is the semantic version just released)
 - add a new entry like `\input{./previous/vx.y.z.tex}` to line 3 of `doc/ReleaseNotes/appendixA.tex`
-- overwrite `develop.tex` with the contents of `doc/ReleaseNotes/vx.y.z-template.tex`
+- clear `develop.toml`
 
-Now new changes can be added to `develop.tex` as development proceeds.
+Now new changes can be added to `develop.toml` as development proceeds until the next release.
 
 **Note**: Newly deprecated MF6IO options are included in the release notes. See the [developer docs](../DEVELOPER.md#deprecation-policy) for more info on MF6's deprecation policy, searching for deprecations among DFNs, and generating a deprecations table for insertion into the release notes.
 

distribution/build_docs.py

@@ -145,7 +145,12 @@ def build_notes_tex(force: bool = False):
         tex_path.unlink(missing_ok=True)
         with set_dir(RELEASE_NOTES_PATH):
             out, err, ret = run_py_script(
-                "mk_releasenotes.py", toml_path, tex_path, verbose=True
+                "mk_releasenotes.py",
+                "--toml",
+                toml_path,
+                "--tex",
+                tex_path,
+                verbose=True,
             )
             assert not ret, out + err
 

doc/ReleaseNotes/mk_releasenotes.py

@@ -13,11 +13,11 @@
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
-    parser.add_argument("toml_path")
-    parser.add_argument("tex_path")
+    parser.add_argument("--toml", default="develop.toml")
+    parser.add_argument("--tex", default="develop.tex")
     args = parser.parse_args()
-    toml_path = Path(args.toml_path).expanduser().absolute()
-    tex_path = Path(args.tex_path).expanduser().absolute()
+    toml_path = Path(args.toml).expanduser().absolute()
+    tex_path = Path(args.tex).expanduser().absolute()
     if not toml_path.is_file():
         warn(f"Release notes TOML file not found: {toml_path}")
         sys.exit(0)

pixi.toml

@@ -113,8 +113,9 @@ build-docs = { cmd = "python build_docs.py", cwd = "distribution" }
 build-dist = { cmd = "python build_dist.py", cwd = "distribution" }
 test-dist-scripts = { cmd = "pytest -v --durations 0", cwd = "distribution" }
 update-version = { cmd = "python update_version.py", cwd = "distribution" }
-deprecations = { cmd = "python deprecations.py", cwd = "doc/mf6io/mf6ivar" }
+collect-deprecations = { cmd = "python deprecations.py", cwd = "doc/mf6io/mf6ivar" }
 check-citations = "cffconvert --validate -i CITATION.cff"
+make-release-notes = { cmd = "python mk_releasenotes.py", cwd = "doc/ReleaseNotes" }
 
 [feature.rtd.tasks]
 sphinx = { cmd = "make html", cwd = ".build_rtd_docs" }