docs: don't version files generated from DFNs (#1946)

It does not seem necessary to version LaTeX, Markdown and .dat files which are autogenerated for the documentation. This PR removes them which removes the need to keep them in sync with DFNs. Also some cleanup in the dist scripts and CI workflows.

Author: wpbonelli

.github/workflows/docs.yml

@@ -89,13 +89,9 @@ jobs:
         working-directory: usgslatex/usgsLaTeX
         run: sudo ./install.sh --all-users
 
-      - name: Test building MF6IO LaTeX from DFNs
-        working-directory: modflow6/distribution
-        run: pixi run pytest -v build_docs.py::test_build_mf6io_tex_from_dfn
-
-      - name: Test building PDFs from LaTeX
-        working-directory: modflow6/distribution
-        run: pixi run pytest -v build_docs.py::test_build_pdfs_from_tex
+      - name: Build MF6IO files from DFNs
+        working-directory: modflow6
+        run: pixi run run-mf6ivar
 
       - name: Setup ${{ env.FC }} ${{ env.FC_V }}
         uses: fortran-lang/setup-fortran@v1
@@ -172,7 +168,7 @@ jobs:
         working-directory: modflow6
         run: pixi run sphinx
 
-      - name: Upload results
+      - name: Upload RTD files
         uses: actions/upload-artifact@v3
         with:
           name: rtd-files-for-${{ github.sha }}
@@ -184,7 +180,22 @@ jobs:
             modflow6/.build_rtd_docs/_mf6io/
             modflow6/.build_rtd_docs/_mf6run/
             modflow6/.build_rtd_docs/_static/
-            
+
+      - name: Build PDF documents
+        working-directory: modflow6
+        run: pixi run build-docs
+
+      - name: Upload PDF documents
+        uses: actions/upload-artifact@v3
+        with:
+          name: mf6io.pdf
+          path: |
+            modflow6/mf6io.pdf
+            modflow6/ReleaseNotes.pdf
+            modflow6/zonebudget.pdf
+            modflow6/converter_mf5to6.pdf
+            modflow6/mf6suptechinfo.pdf
+            modflow6/mf6examples.pdf
 
   rtd_trigger:
     name: rtd-trigger

.gitignore

@@ -118,6 +118,9 @@ html/
 xml/
 distribution/run-time-comparison.md
 doc/ReleaseNotes/run-time-comparison.tex
+doc/ReleaseNotes/deprecations.tex
+doc/mf6io/mf6ivar/md
+doc/mf6io/mf6ivar/tex
 
 # Intel Fortran Visual Studio intermediate files
 msvs/*.fdz

DEVELOPER.md

@@ -196,7 +196,7 @@ Visual Studio installers can be downloaded from the [official website](https://v
 
 *Doxygen & LaTeX*
 
-[Doxygen](https://www.doxygen.nl/index.html) is used to generate the [MODFLOW 6 source code documentation](https://modflow-usgs.github.io/modflow6/). [Graphviz](https://graphviz.org/) is used by doxygen to produce source code diagrams. [LaTeX](https://www.latex-project.org/) is used to generate the MODFLOW 6 release notes and Input/Output documents (docs/mf6io/mf6io.nightlybuild).
+[Doxygen](https://www.doxygen.nl/index.html) is used to generate the [MODFLOW 6 source code documentation](https://modflow-usgs.github.io/modflow6/). [Graphviz](https://graphviz.org/) is used by doxygen to produce source code diagrams. [LaTeX](https://www.latex-project.org/) is used to generate the MODFLOW 6 release notes and Input/Output documents.
 
 These programs can be installed from various sources, including by conda, macports, or from individual sources such as https://www.tug.org/. Details about USGS LaTeX libraries can be seen in addition to linux installs in the CI workflow for the docs (`.github/workflows/ci-docs.yml`).
 

distribution/benchmark.py

@@ -17,19 +17,17 @@
 
 from utils import get_project_root_path
 
-_verify = False
-_project_root_path = get_project_root_path()
-_examples_repo_path = _project_root_path.parent / "modflow6-examples"
-_build_path = _project_root_path / "builddir"
-_bin_path = _project_root_path / "bin"
-_github_repo = "MODFLOW-USGS/modflow6"
-_markdown_file_name = "run-time-comparison.md"
-_is_windows = sys.platform.lower() == "win32"
-_app_ext = ".exe" if _is_windows else ""
-_soext = ".dll" if _is_windows else ".so"
-_ostag = (
+PROJ_ROOT_PATH = get_project_root_path()
+EXAMPLES_REPO_PATH = PROJ_ROOT_PATH.parent / "modflow6-examples"
+BUILD_PATH = PROJ_ROOT_PATH / "builddir"
+BIN_PATH = PROJ_ROOT_PATH / "bin"
+GITHUB_REPO = "MODFLOW-USGS/modflow6"
+BENCHMARKS_FILE_NAME = "run-time-comparison.md"
+IS_WINDOWS = sys.platform.lower() == "win32"
+EXE_EXT = ".exe" if IS_WINDOWS else ""
+OSTAG = (
     "win64"
-    if _is_windows
+    if IS_WINDOWS
     else "linux"
     if sys.platform.lower().startswith("linux")
     else "mac"
@@ -38,10 +36,10 @@
 
 def download_previous_version(output_path: PathLike) -> Tuple[str, Path]:
     output_path = Path(output_path).expanduser().absolute()
-    version = get_latest_version(_github_repo)
-    distname = f"mf{version}_{_ostag}"
+    version = get_latest_version(GITHUB_REPO)
+    distname = f"mf{version}_{OSTAG}"
     url = (
-        f"https://github.com/{_github_repo}"
+        f"https://github.com/{GITHUB_REPO}"
         + f"/releases/download/{version}/{distname}.zip"
     )
     download_and_unzip(
@@ -294,7 +292,7 @@ def write_results(
     previous_v = get_mf6_version(previous_exe)
 
     # open markdown table
-    with open(output_path / _markdown_file_name, "w") as f:
+    with open(output_path / BENCHMARKS_FILE_NAME, "w") as f:
         # get version numbers and write header
 
         line = "### Benchmarks\n\n"
@@ -361,14 +359,14 @@ def run_benchmarks(
     #     print(f"Benchmark results already exist: {results_path}")
     #     return
 
-    exe_name = f"mf6{_app_ext}"
+    exe_name = f"mf6{EXE_EXT}"
     current_exe = current_bin_path / exe_name
     previous_exe = previous_bin_path / exe_name
 
     if not current_exe.is_file():
         print("Building current MODFLOW 6 development version")
         meson_build(
-            project_path=_project_root_path,
+            project_path=PROJ_ROOT_PATH,
             build_path=build_path,
             bin_path=current_bin_path,
         )
@@ -418,14 +416,14 @@ def run_benchmarks(
 @pytest.mark.skip(reason="for manual testing")
 def test_run_benchmarks(tmp_path):
     run_benchmarks(
-        build_path=_build_path,
-        current_bin_path=_bin_path,
-        previous_bin_path=_bin_path / "rebuilt",
-        examples_path=_examples_repo_path / "examples",
+        build_path=BUILD_PATH,
+        current_bin_path=BIN_PATH,
+        previous_bin_path=BIN_PATH / "rebuilt",
+        examples_path=EXAMPLES_REPO_PATH / "examples",
         output_path=tmp_path,
         excluded=["previous"],
     )
-    assert (tmp_path / _markdown_file_name).is_file()
+    assert (tmp_path / BENCHMARKS_FILE_NAME).is_file()
 
 
 if __name__ == "__main__":
@@ -442,33 +440,33 @@ def test_run_benchmarks(tmp_path):
     parser.add_argument(
         "--build-path",
         required=False,
-        default=str(_build_path),
+        default=str(BUILD_PATH),
         help="Path to the build workspace",
     )
     parser.add_argument(
         "--current-bin-path",
         required=False,
-        default=str(_bin_path),
+        default=str(BIN_PATH),
         help="Path to the directory to install current version executables",
     )
     parser.add_argument(
         "--previous-bin-path",
         required=False,
-        default=str(_bin_path / "rebuilt"),
+        default=str(BIN_PATH / "rebuilt"),
         help="Path to the directory to install previous version executables",
     )
     parser.add_argument(
         "-o",
         "--output-path",
         required=False,
-        default=str(_project_root_path / "distribution" / ""),
+        default=str(PROJ_ROOT_PATH / "distribution" / ""),
         help="Location to create the zip archive",
     )
     parser.add_argument(
         "-e",
         "--examples-repo-path",
         required=False,
-        default=str(_project_root_path.parent / "modflow6-examples"),
+        default=str(PROJ_ROOT_PATH.parent / "modflow6-examples"),
         help="Path to the directory with modflow6 examples",
     )
     args = parser.parse_args()
@@ -481,7 +479,7 @@ def test_run_benchmarks(tmp_path):
     examples_repo_path = (
         Path(args.examples_repo_path)
         if args.examples_repo_path
-        else _examples_repo_path
+        else EXAMPLES_REPO_PATH
     )
 
     output_path.mkdir(parents=True, exist_ok=True)