fix: Correct Read The Docs build failures

.github/workflows/doc-test.yml

@@ -1,18 +1,46 @@
 name: "Pull Request Docs Check"
-on: 
-- pull_request
+
+on:
+  pull_request
 
 # Cancels in-progress workflows for a PR when updated
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  docs:
-    runs-on: ubuntu-latest
+  docs-build:
+    # Use the same OS as Read the Docs
+    runs-on: ubuntu-22.04
+
     steps:
-    - uses: actions/checkout@v1
-    - uses: ammaraskar/sphinx-action@dev
-      with:
-        docs-folder: "docs/"
-        build-command: "sphinx-build -b html . _build -W"
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          # Use the same Python version as Read the Docs
+          python-version: "3.10"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          # Use the same Node.js version as Read the Docs
+          node-version: "16"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends plantuml texlive npm
+
+      - name: Install Node.js packages
+        run: |
+          npm install -g npm@9.8.1
+          npm install -g @mermaid-js/mermaid-cli@10.3.1
+
+      - name: Install Python dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build documentation with Sphinx
+        run: sphinx-build -b html docs/ docs/_build -W

docs/conf.py

@@ -50,9 +50,8 @@
 ]
 
 autoclass_content = 'both'
-autodoc_mock_imports = [ "ats", "colorcet", "h5py", "lxml", "matplotlib", "meshio", "mpi4py", "numba", "pandas",
-                         "paraview", "pygeosx", "pyevtk", "pylvarray", "scipy", "segyio", "vtk", "xmlschema",
-                         "xmltodict", "xsdata" ]
+autodoc_mock_imports = [ "ats", "colorcet", "meshio", "mpi4py", "numba", "paraview", "pygeosx",
+                         "pyevtk", "pylvarray", "scipy", "segyio", "xmltodict", "xsdata" ]
 autodoc_typehints = 'none'
 autodoc_typehints_format = 'short'
 suppress_warnings = [ "autodoc.mocked_object" ]

docs/requirements.txt

@@ -1,7 +1,7 @@
-sphinx >= 8.2
+sphinx < 8.2
 sphinx_rtd_theme >= 3.0
 sphinx-argparse >= 0.5
-sphinx-autodoc-typehints >= 3.1
+sphinx-autodoc-typehints < 3.1
 sphinx-design >= 0.6
 # Running CLI programs and capture outputs
 sphinxcontrib-programoutput >= 0.17
@@ -12,8 +12,9 @@ tqdm >= 4.67
 numpy >= 2.2
 pandas >= 2.2
 typing_extensions > 4.12
-matplotlib>=3.9.4
+matplotlib ~= 3.9.0
 h5py >= 3.12
 lxml >= 4.5.0
 parameterized >= 0.9
 pyvista >= 0.44
+xmlschema