From ee95be1c54745045beb1eeabb227e735d2e53458 Mon Sep 17 00:00:00 2001
From: Kyle Mandli <kyle.mandli@gmail.com>
Date: Thu, 10 Sep 2026 11:09:12 -0400
Subject: [PATCH 1/2] Install the multiprocessing run helpers

Signed-off-by: Kyle Mandli <kyle.mandli@gmail.com>
Assisted-by: claude claude-opus-5[1m]
---
 src/python/clawutil/meson.build     |  3 +++
 src/python/clawutil/run_examples.py | 30 +++++++++++++++++++----------
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/src/python/clawutil/meson.build b/src/python/clawutil/meson.build
index f7b1330..dc7634f 100644
--- a/src/python/clawutil/meson.build
+++ b/src/python/clawutil/meson.build
@@ -7,14 +7,17 @@ python_sources = [
   'chardiff.py',
   'clawcode2html.py',
   'claw_git_status.py',
+  'clawmultip_tools.py',
   'convert_readme.py',
   'data.py',
   'git.py',
   'imagediff.py',
   'make_all.py',
+  'multip_tools.py',
   'nbtools.py',
   'regression_tests.py',
   'runclaw.py',
+  'run_examples.py',
   'setenv.py',
   'test.py',
   'util.py',
diff --git a/src/python/clawutil/run_examples.py b/src/python/clawutil/run_examples.py
index c28f7ca..dbe142c 100644
--- a/src/python/clawutil/run_examples.py
+++ b/src/python/clawutil/run_examples.py
@@ -8,24 +8,34 @@
     make_all_errors.txt
 will be created that contain the output normally sent to the screen and any
 error messages from running the examples.
+
+Invoke either as a script or, once Clawpack is installed, with
+
+    python -m clawpack.clawutil.run_examples
 """
 
 from clawpack.clawutil import make_all
 import os
 
-# run examples with the user's current environment by default:
-env = os.environ
+# Guarded so that importing this module does not build and run every example
+# in the current directory -- it is installed alongside the rest of clawutil,
+# and anything that imports the package (autodoc, an import check) would
+# otherwise trigger a full run.
+if __name__ == '__main__':
+
+    # run examples with the user's current environment by default:
+    env = os.environ
 
-# Explicitly set some environment variables, if desired, e.g.:
-#env['GIT_STATUS'] = 'True'
-#env['FFLAGS'] = '-O2 -fopenmp'
-#env['OMP_NUM_THREADS'] = '6'
+    # Explicitly set some environment variables, if desired, e.g.:
+    #env['GIT_STATUS'] = 'True'
+    #env['FFLAGS'] = '-O2 -fopenmp'
+    #env['OMP_NUM_THREADS'] = '6'
 
-make_all.make_all(make_clean_first=True, env=env)
+    make_all.make_all(make_clean_first=True, env=env)
 
-run_notebooks = True  # run any *.ipynb files and create html versions?
+    run_notebooks = True  # run any *.ipynb files and create html versions?
 
-if run_notebooks:
-    make_all.make_notebook_htmls(env=env)
+    if run_notebooks:
+        make_all.make_notebook_htmls(env=env)
 
 

From add1396e6602c817e38a5722a9b47cad92c34d69 Mon Sep 17 00:00:00 2001
From: Kyle Mandli <kyle.mandli@gmail.com>
Date: Thu, 10 Sep 2026 11:40:05 -0400
Subject: [PATCH 2/2] Do not install convert_readme.py, which runs at import

Signed-off-by: Kyle Mandli <kyle.mandli@gmail.com>
Assisted-by: claude claude-opus-5[1m]
---
 src/python/clawutil/meson.build | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/python/clawutil/meson.build b/src/python/clawutil/meson.build
index dc7634f..ac954a8 100644
--- a/src/python/clawutil/meson.build
+++ b/src/python/clawutil/meson.build
@@ -8,7 +8,10 @@ python_sources = [
   'clawcode2html.py',
   'claw_git_status.py',
   'clawmultip_tools.py',
-  'convert_readme.py',
+  # convert_readme.py is deliberately not installed: its body runs at import
+  # (it reads README.rst from the working directory, or calls sys.exit), so it
+  # cannot be used as a module.  Makefile.common, apps/notebooks/Makefile and
+  # doc's application_documentation.rst all invoke it by $CLAW path instead.
   'data.py',
   'git.py',
   'imagediff.py',