refactor: mesh-doctor as a package (#183)

* Create package

* Add annotations from __future__

* Update all documentation and install procedures

* Improve mesh-doctor command line

* Use meshAction instead of action in allChecks and mainChecks to avoid redundant reading of input file

* Correct skipped tests

Author: alexbenedicto

.github/workflows/README.md

@@ -29,6 +29,7 @@ Tests each Python package independently to ensure:
 - `geos-xml-tools` - XML preprocessing and formatting
 - `geos-xml-viewer` - XML viewing tools
 - `hdf5-wrapper` - HDF5 file handling wrapper
+- `mesh-doctor` - Tools to perform checks on vtkUnstructuredGrids
 - `pygeos-tools` - GEOS Python tools
 
 ### Jobs
@@ -240,9 +241,10 @@ GEOS integration tests are **automatically triggered** when changes affect:
 
 #### GEOS-Integrated Packages
 - `geos-utils/` - Core utilities used of goesPythonPackages
-- `geos-mesh/` - Mesh conversion (`convert_abaqus`, `mesh-doctor`)
+- `geos-mesh/` - Mesh conversion (`convert_abaqus`)
 - `geos-xml-tools/` - XML preprocessing (`preprocess_xml`, `format_xml`)
 - `hdf5-wrapper/` - HDF5 I/O wrapper
+- `mesh-doctor/` - Checks of vtkUnstructuredGrid before using in GEOS
 - `pygeos-tools/` - Python tools for GEOS
 - `geos-ats/` - Automated testing framework
 
@@ -305,7 +307,6 @@ The CI uses the following decision matrix:
 ✅ **Tests Will Run (Required + Label)**
 ```
 Changes:
-  - geos-mesh/src/mesh_converter.py
   - geos-xml-tools/src/preprocessor.py
 Labels: test-geos-integration
 Result: GEOS integration will run (changes affect integrated packages)
@@ -374,6 +375,7 @@ Result: GEOS integration forced (tests will run regardless of changes)
 │    pip install geos-mesh                    │
 │    pip install geos-xml-tools               │
 │    pip install hdf5-wrapper                 │
+│    pip install mesh-doctor                  │
 │    pip install pygeos-tools                 │
 │    pip install geos-ats                     │
 └─────────────────────────────────────────────┘
@@ -402,9 +404,10 @@ Result: GEOS integration forced (tests will run regardless of changes)
 |       Package      |                        Tools                        |                               Purpose                               |
 |--------------------|-----------------------------------------------------|---------------------------------------------------------------------|
 | **geos-xml-tools** | `preprocess_xml`;`format_xml`                       | Preprocess XML input files;Format XML for readability               |
-| **geos-mesh**      | `convert_abaqus`;`mesh-doctor`                      | Convert Abaqus meshes to VTU/GMSH;Validate and fix mesh quality     |
+| **geos-mesh**      | `convert_abaqus`;`mesh-doctor`                      | Convert Abaqus meshes to VTU/GMSH                                   |
 | **geos-ats**       | `run_geos_ats`;`setup_ats_environment`;`geos_ats_*` | Run automated test suite;Setup test environment;Various test checks |
 | **hdf5-wrapper**   | Python API                                          | HDF5 file I/O operations                                            |
+| **mesh-doctor**    | `mesh-doctor`                                       | Validate and fix mesh quality                                       |
 | **pygeos-tools**   | Python API                                          | GEOS workflow utilities                                             |
 | **geos-utils**     | Python API                                          | Common utility functions                                            |
 

.github/workflows/python-package.yml

@@ -68,6 +68,7 @@ jobs:
           - geos-trame
           - geos-xml-tools
           - geos-xml-viewer
+          - mesh-doctor
           - hdf5-wrapper
           - pygeos-tools
         include:
@@ -77,6 +78,8 @@ jobs:
             dependencies: "geos-utils geos-geomechanics"
           - package-name: geos-processing
             dependencies: "geos-utils geos-mesh geos-geomechanics"
+          - package-name: mesh-doctor
+            dependencies: "geos-utils geos-mesh"
           - package-name: pygeos-tools
             dependencies: "geos-utils geos-mesh"
           - package-name: geos-timehistory
@@ -201,6 +204,7 @@ jobs:
           "geos-mesh"
           "geos-xml-tools"
           "hdf5-wrapper"
+          "mesh-doctor"
           "pygeos-tools"
           "geos-ats"
         )

.github/workflows/typing-check.yml

@@ -16,7 +16,7 @@ jobs:
       max-parallel: 3
       matrix:
         # add packages to check typing
-        package-name: ["geos-geomechanics", "geos-processing", "geos-timehistory", "geos-utils", "geos-trame", "geos-xml-tools", "hdf5-wrapper"]
+        package-name: ["geos-geomechanics", "geos-processing", "geos-timehistory", "geos-utils", "geos-trame", "geos-xml-tools", "hdf5-wrapper", "mesh-doctor"]
 
     steps:
     - uses: actions/checkout@v4

README.md

@@ -73,8 +73,8 @@ GEOS Python packages dependency tree (inter-dependency and main external depende
 │   └── hdf5-wrapper
 |
 ├── mesh-doctor
-│   ├── geos-prep
-│   └── pyvista
+│   ├── geos-utils
+│   └── geos-mesh
 |
 ├── geos-trame
 │   ├── geos-xml-tools

docs/conf.py

@@ -14,20 +14,43 @@
 #
 import os
 import sys
+import subprocess
 
 # Add python modules to be documented
 python_root = '..'
 python_modules = ( 'geos-ats', 'geos-geomechanics', 'geos-mesh', 'geos-processing', 'geos-pv', 'geos-timehistory',
-                   'geos-utils', 'geos-xml-tools', 'geos-xml-viewer', 'hdf5-wrapper', 'pygeos-tools' )
+                   'geos-utils', 'geos-xml-tools', 'geos-xml-viewer', 'hdf5-wrapper', 'mesh-doctor', 'pygeos-tools' )
 
 
 for m in python_modules:
     sys.path.insert( 0, os.path.abspath( os.path.join( python_root, m, 'src' ) ) )
 
+# Install mesh-doctor in editable mode if not already available
+# This ensures mesh-doctor command is available for sphinxcontrib.programoutput
+try:
+    subprocess.run( [ sys.executable, '-m', 'geos.mesh_doctor.cli', '--help' ],
+                    capture_output=True, check=True, timeout=5 )
+except ( subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError ):
+    # mesh-doctor not available, install it and its dependencies in editable mode
+    print( "Installing mesh-doctor dependencies for documentation generation..." )
+    packages_to_install = [ 'geos-utils', 'geos-mesh', 'mesh-doctor' ]
+    for pkg in packages_to_install:
+        pkg_path = os.path.abspath( os.path.join( python_root, pkg ) )
+        try:
+            print( f"  Installing {pkg}..." )
+            subprocess.run( [ sys.executable, '-m', 'pip', 'install', '-e', pkg_path ],
+                            check=True, capture_output=True )
+        except subprocess.CalledProcessError as e:
+            print( f"Warning: Could not install {pkg}: {e}" )
+            print( "Documentation may be incomplete." )
+            break
+    else:
+        print( "mesh-doctor installed successfully." )
+
 # -- Project information -----------------------------------------------------
 
 project = u'GEOS Python Packages'
-copyright = u'2018-2024 Lawrence Livermore National Security, The Board of Trustees of the Leland Stanford Junior University, TotalEnergies, and GEOSX Contributors.'
+copyright = u'2018-2025 Lawrence Livermore National Security, The Board of Trustees of the Leland Stanford Junior University, TotalEnergies, and GEOS Contributors.'
 author = u'GEOS Contributors'
 
 # The short X.Y version

docs/geos-mesh.rst

@@ -7,8 +7,6 @@ GEOS Mesh tools
       :maxdepth: 1
       :caption: Contents:
 
-      ./geos_mesh_docs/doctor
-
       ./geos_mesh_docs/converter
 
       ./geos_mesh_docs/io