docs(rtd): introduce migration guide page (#2287)

wpbonelli · web-flow · commit 0339d5943d27 · 2025-04-21T09:56:22.000-04:00
The MF6.6.0 PRT migration guide was shown in the API docs site rather than the RTD, because it's located in the src/ directory. Introduce a new page on the RTD site for version-specific migration guides and add a step copying the guide to the docs directory before building the RTD site. We currently do this for several files scattered throughout the repo — maybe eventually we can consolidate all or most of these in the docs folder. In the longer term, we have discussed consolidating our RTD and PDF docs. Maybe at that point migration guides can become part of the release notes PDF too.

Also add the extended build docs to the developer section, and fix a lingering reference to the old organization name.
diff --git a/.build_rtd_docs/conf.py b/.build_rtd_docs/conf.py
@@ -44,51 +44,64 @@
 # -- import version from doc/version.py -------------------------------------
 from version import __version__
 
-# -- copy run-time comparison markdown --------------------------------------
-print("Copy the run-time comparison table")
 dstdir = "_mf6run"
-fpth = "run-time-comparison.md"
-src = os.path.join("..", "distribution", fpth)
-dst = os.path.join(dstdir, fpth)
-# clean up an existing _mf6run directory
 if os.path.isdir(dstdir):
     shutil.rmtree(dstdir)
-# make the _mf6run directory
 os.makedirs(dstdir)
-# copy the file
+
+print(f"Copy run-time comparison table to {dstdir}")
+fpth = "run-time-comparison.md"
+src = os.path.join("..", "distribution", fpth)
+dst = os.path.join(dstdir, fpth)
 shutil.copy(src, dst)
 
-# -- copy developer docs
 dstdir = "_dev"
-fpth = "DEVELOPER.md"
-src = os.path.join("..", fpth)
-dst = os.path.join(dstdir, fpth.lower())
-# clean up an existing _mf6run directory
 if os.path.isdir(dstdir):
     shutil.rmtree(dstdir)
-# make the directory
 os.makedirs(dstdir)
-# copy the file
+
+print(f"Copy developer docs to {dstdir}")
+fpth = "DEVELOPER.md"
+src = os.path.join("..", fpth)
+dst = os.path.join(dstdir, fpth)
 shutil.copy(src, dst)
 
-# -- copy contributor docs
 fpth = "CONTRIBUTING.md"
 src = os.path.join("..", fpth)
-dst = os.path.join(dstdir, fpth.lower())
+dst = os.path.join(dstdir, fpth)
 shutil.copy(src, dst)
 
-# -- copy style guide
 fpth = "styleguide.md"
 src = os.path.join(fpth)
 dst = os.path.join(dstdir, fpth)
 shutil.copy(src, dst)
 
-# -- copy DFN spec
 fpth = "readme.md"
 src = os.path.join("..", "doc", "mf6io", "mf6ivar", fpth)
 dst = os.path.join(dstdir, "dfn.md")
 shutil.copy(src, dst)
 
+fpth = "EXTENDED.md"
+src = os.path.join("..", fpth)
+dst = os.path.join(dstdir, fpth)
+shutil.copy(src, dst)
+
+fpth = "CODE_OF_CONDUCT.md"
+src = os.path.join("..", fpth)
+dst = os.path.join(dstdir, fpth)
+shutil.copy(src, dst)
+
+dstdir = "_migration"
+if os.path.isdir(dstdir):
+    shutil.rmtree(dstdir)
+os.makedirs(dstdir)
+
+print(f"Copy migration guides to {dstdir}")
+fpth = "mf6_6_0_prt_migration_guide.md"
+src = os.path.join("..", "src", "Solution", "ParticleTracker", fpth)
+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")
@@ -168,6 +181,7 @@
     "nbsphinx_link",
     "myst_parser",
     "sphinx_markdown_tables",
+    "sphinxcontrib.mermaid",
 ]
 
 # # Tell sphinx what the pygments highlight language should be.
diff --git a/.build_rtd_docs/dev.rst b/.build_rtd_docs/dev.rst
@@ -1,13 +1,15 @@
 Developer Guide
 ---------------
 
-This section includes developer instructions and conventions.
+This section contains developer documentation, including contributor conventions, instructions for common tasks, internal specifications, and more.
 
 .. toctree::
    :maxdepth: 1
    :glob:
 
-   _dev/contributing.md
-   _dev/developer.md
+   _dev/CODE_OF_CONDUCT.md
+   _dev/CONTRIBUTING.md
+   _dev/DEVELOPER.md
+   _dev/EXTENDED.md
    _dev/styleguide.md
    _dev/dfn.md
diff --git a/.build_rtd_docs/index.rst b/.build_rtd_docs/index.rst
@@ -16,4 +16,4 @@ Contents:
    _mf6run/deprecations.md
    mf6io
    dev
-
+   migration
diff --git a/.build_rtd_docs/migration.rst b/.build_rtd_docs/migration.rst
@@ -0,0 +1,10 @@
+Migration Guides
+----------------
+
+This section includes version-specific migration guides for particular models and/or capabilities.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   _migration/mf6_6_0_prt_migration_guide
diff --git a/.build_rtd_docs/styleguide.md b/.build_rtd_docs/styleguide.md
@@ -1,4 +1,4 @@
-# Fortran Style Guide
+# MODFLOW 6 Fortran style guide
 
 The goal of this guide is to provide a standard for MODFLOW 6 contributors to follow, in pursuit of consistent, readable, well-organized, and unsurprising source code.
 
diff --git a/.gitignore b/.gitignore
@@ -114,6 +114,7 @@ CMakeFiles/
 .build_rtd_docs/_mf6src
 .build_rtd_docs/_mf6run
 .build_rtd_docs/_dev
+.build_rtd_docs/_migration
 latex/
 html/
 xml/
diff --git a/CITATION.cff b/CITATION.cff
@@ -3,7 +3,7 @@ message: If you use this software, please cite the software itself.
 type: software
 title: MODFLOW 6 Modular Hydrologic Model
 version: 6.7.0.dev1
-date-released: '2025-02-10'
+date-released: '2025-04-21'
 doi: 10.5066/F76Q1VQV
 abstract: MODFLOW 6 is an object-oriented program and framework developed to provide
   a platform for supporting multiple models and multiple types of models within the
diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -1,8 +1,8 @@
 # Developing MODFLOW 6
 
-This document describes how to set up a development environment to modify, build and test MODFLOW 6. Details on how to contribute your code to the repository are found in the separate document [CONTRIBUTING.md](CONTRIBUTING.md). 
+This document describes how to set up a development environment to modify, build and test MODFLOW 6. Details on how to contribute your code to the repository are found in the separate document [CONTRIBUTING.md](./CONTRIBUTING.md). 
 
-To build and test an extended version of the program, first read the instructions below and then continue in [EXTENDED.md](EXTENDED.md).
+To build and test an extended version of the program, first read the instructions below and then continue in [EXTENDED.md](./EXTENDED.md).
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
diff --git a/EXTENDED.md b/EXTENDED.md
@@ -1,4 +1,4 @@
-# Developing in extended MODFLOW 6
+# Developing extended MODFLOW 6
 
 This document describes how to set up your build environment for developing and testing the extended version of MODFLOW. It further builds on the instructions given in [DEVELOPER.md](DEVELOPER.md) so make sure to read those first.
 
@@ -118,7 +118,7 @@ Extended MODFLOW was designed to have all third party functionality (MPI, PETSc
 
 ---
 
-## Testing the extended of MODFLOW 6
+## Testing the extended version of MODFLOW 6
 
 Extended MODFLOW can be tested using the same test framework as the serial program, with just a few modifications. To run a test inside the `autotest` folder in parallel mode, make sure to add a marker `@pytest.mark.parallel` so that the test is only executed in the Continuous Integration when running a configuration with an extended build of MODFLOW. Similarly, adding the marker `@pytest.mark.netcdf` to a test ensures that the test will only be executed when intended by specifying NetCDF test mode.
 
diff --git a/code.json b/code.json
@@ -20,7 +20,7 @@
         "laborHours": -1,
         "version": "6.7.0.dev1",
         "date": {
-            "metadataLastUpdated": "2025-02-10"
+            "metadataLastUpdated": "2025-04-21"
         },
         "organization": "U.S. Geological Survey",
         "permissions": {
diff --git a/distribution/build_docs.py b/distribution/build_docs.py
@@ -355,7 +355,7 @@ def test_build_pdfs_from_tex(tmp_path):
 
 
 def fetch_example_docs(
-    out_path: PathLike, force: bool = False, repo_owner: str = "MODFLOW-USGS"
+    out_path: PathLike, force: bool = False, repo_owner: str = "MODFLOW-ORG"
 ):
     pdf_name = "mf6examples.pdf"
     if force or not (out_path / pdf_name).is_file():
diff --git a/doc/version.py b/doc/version.py
@@ -1,3 +1,3 @@
 # MODFLOW 6 version file automatically created using...update_version.py
-# created on...February 10, 2025 20:19:09
+# created on...April 21, 2025 09:11:08
 __version__ = "6.7.0.dev1"
diff --git a/doc/version.tex b/doc/version.tex
@@ -1,3 +1,3 @@
 \newcommand{\modflowversion}{mf6.7.0.dev1}
-\newcommand{\modflowdate}{February 10, 2025}
+\newcommand{\modflowdate}{April 21, 2025}
 \newcommand{\currentmodflowversion}{Version \modflowversion---\modflowdate}
diff --git a/pixi.lock b/pixi.lock
diff --git a/pixi.toml b/pixi.toml
@@ -51,6 +51,7 @@ ipython = "*"
 ipykernel = "*"
 myst-parser = "*"
 sphinx_rtd_theme = ">=1"
+sphinxcontrib-mermaid = "*"
 pytest = "*"
 filelock = "*"
 modflow-devtools = "*"
diff --git a/src/Solution/ParticleTracker/mf6_6_0_prt_migration_guide.md b/src/Solution/ParticleTracker/mf6_6_0_prt_migration_guide.md
@@ -133,7 +133,7 @@ Diagrams use the following conventions.
 * Green outcome boxes indicate the particle remains active.
 * Red outcome boxes indicate the particle terminates.
 
-```mermaid
+```{mermaid}
 flowchart LR
      OPTION[Outcome]
     OPTION(OPTION) ==> |Yes| STEP([Step])
@@ -158,7 +158,7 @@ If the cell into which the particle is being released is active, the particle wi
 
 Note that for a dry-but-active cell the `DRAPE` option has no effect. In that case, the particle is released into the cell, and its subsequent behavior can be configured using the `DRY_TRACKING_METHOD` option discussed below.
 
-```mermaid
+```{mermaid}
 flowchart LR
     ACTIVE --> |No| DRAPE(DRAPE)
     ACTIVE{Cell active?} --> |Yes| RELEASE[Release in specified cell]:::release
@@ -189,7 +189,7 @@ If `STOP` is selected, dry particles will be terminated.
 
 If `STAY` is selected, a dry particle will remain stationary until a) the water table rises and tracking can continue, b) the particle terminates due to reaching its `STOPTIME` or `STOPTRAVELTIME`, or c) the simulation ends.
 
-```mermaid
+```{mermaid}
 flowchart LR
     ACTIVE{Cell active?} --> |No| TERMINATE{Terminate}
     ACTIVE{Cell active?} --> |Yes| PARTICLE_DRY
diff --git a/src/Utilities/version.f90 b/src/Utilities/version.f90
@@ -18,7 +18,7 @@ module VersionModule
   ! -- modflow 6 version
   integer(I4B), parameter :: IDEVELOPMODE = 1
   character(len=*), parameter :: VERSIONNUMBER = '6.7.0.dev1'
-  character(len=*), parameter :: VERSIONTAG = ' (preliminary) 02/10/2025'
+  character(len=*), parameter :: VERSIONTAG = ' (preliminary) 04/21/2025'
   character(len=40), parameter :: VERSION = VERSIONNUMBER//VERSIONTAG
   character(len=2), parameter :: MFVNAM = ' 6'
   character(len=*), parameter :: MFTITLE = &

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Fortran Style Guide`
	`1`	`+# MODFLOW 6 Fortran style guide`
`2`	`2`
`3`	`3`	`The goal of this guide is to provide a standard for MODFLOW 6 contributors to follow, in pursuit of consistent, readable, well-organized, and unsurprising source code.`
`4`	`4`