From dd73b459e3a7112d922c38e0d72b547a7c36ffb5 Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 16:51:10 +0100 Subject: [PATCH 1/8] Fix docs build in CI by running sphinx-build directly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Run sphinx-build directly instead of through main.py wrapper - Add sys.exit(1) in main.py when docs build fails for local use 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/docs.yml | 3 +-- main.py | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8ecd9e3..cba6955 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,8 +49,7 @@ jobs: - name: Build Sphinx docs env: PYVISTA_OFF_SCREEN: "true" - PYTHONPATH: "${{ github.workspace }}" - run: uv run python main.py --docs + run: uv run sphinx-build -b html docs/source docs/build/html - name: Upload artifact if: github.ref == 'refs/heads/main' diff --git a/main.py b/main.py index cd23562..edcabcb 100644 --- a/main.py +++ b/main.py @@ -500,7 +500,8 @@ def main(): # Handle documentation commands if args.docs: - build_docs() + if not build_docs(): + sys.exit(1) if __name__ == "__main__": From 940aca82923bf7bc3ec0053ac628507c2cb1baa0 Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 16:54:38 +0100 Subject: [PATCH 2/8] Add PYTHONPATH to include src/ for Poisson module --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cba6955..d6f052f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,6 +49,7 @@ jobs: - name: Build Sphinx docs env: PYVISTA_OFF_SCREEN: "true" + PYTHONPATH: "${{ github.workspace }}/src" run: uv run sphinx-build -b html docs/source docs/build/html - name: Upload artifact From 149c814ab13f947a7925889e54d8036ccc0b63b0 Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 16:57:50 +0100 Subject: [PATCH 3/8] Set PYTHONPATH inline before uv run --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d6f052f..e584caa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,8 +49,7 @@ jobs: - name: Build Sphinx docs env: PYVISTA_OFF_SCREEN: "true" - PYTHONPATH: "${{ github.workspace }}/src" - run: uv run sphinx-build -b html docs/source docs/build/html + run: PYTHONPATH="${{ github.workspace }}/src" uv run sphinx-build -b html docs/source docs/build/html - name: Upload artifact if: github.ref == 'refs/heads/main' From 754342c053acf912985c5780713680fb5ab0724b Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 17:00:41 +0100 Subject: [PATCH 4/8] Use python -m sphinx with export PYTHONPATH --- .github/workflows/docs.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e584caa..8ebeda1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,7 +49,9 @@ jobs: - name: Build Sphinx docs env: PYVISTA_OFF_SCREEN: "true" - run: PYTHONPATH="${{ github.workspace }}/src" uv run sphinx-build -b html docs/source docs/build/html + run: | + export PYTHONPATH="${{ github.workspace }}/src:$PYTHONPATH" + uv run python -m sphinx -b html docs/source docs/build/html - name: Upload artifact if: github.ref == 'refs/heads/main' From 9b9966bae3b0162caa52f208adb8b6b250cb22e4 Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 17:03:24 +0100 Subject: [PATCH 5/8] Add src to sys.path in Python before running sphinx --- .github/workflows/docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8ebeda1..068e738 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -50,8 +50,9 @@ jobs: env: PYVISTA_OFF_SCREEN: "true" run: | - export PYTHONPATH="${{ github.workspace }}/src:$PYTHONPATH" - uv run python -m sphinx -b html docs/source docs/build/html + echo "Checking if Poisson module is importable..." + uv run python -c "import sys; sys.path.insert(0, '${{ github.workspace }}/src'); import Poisson; print('Poisson imported from:', Poisson.__file__)" + uv run python -c "import sys; sys.path.insert(0, '${{ github.workspace }}/src'); from sphinx.cmd.build import main; sys.exit(main(['-b', 'html', 'docs/source', 'docs/build/html']))" - name: Upload artifact if: github.ref == 'refs/heads/main' From f084572dda28847335c8ef6125bc94e3434e526f Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 17:06:25 +0100 Subject: [PATCH 6/8] Mock mpi4py, h5py, numba for docs build without MPI --- .github/workflows/docs.yml | 6 ++---- docs/source/conf.py | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 068e738..d6f052f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,10 +49,8 @@ jobs: - name: Build Sphinx docs env: PYVISTA_OFF_SCREEN: "true" - run: | - echo "Checking if Poisson module is importable..." - uv run python -c "import sys; sys.path.insert(0, '${{ github.workspace }}/src'); import Poisson; print('Poisson imported from:', Poisson.__file__)" - uv run python -c "import sys; sys.path.insert(0, '${{ github.workspace }}/src'); from sphinx.cmd.build import main; sys.exit(main(['-b', 'html', 'docs/source', 'docs/build/html']))" + PYTHONPATH: "${{ github.workspace }}/src" + run: uv run sphinx-build -b html docs/source docs/build/html - name: Upload artifact if: github.ref == 'refs/heads/main' diff --git a/docs/source/conf.py b/docs/source/conf.py index d2e33be..a568c8e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,8 +52,8 @@ "show-inheritance": True, } -# Mock heavy runtime dependencies -# autodoc_mock_imports = ["numba", "pyarrow", "matplotlib"] # Disabled - causing import issues +# Mock heavy runtime dependencies that may not be available during docs build +autodoc_mock_imports = ["mpi4py", "h5py", "numba"] # -- Numpydoc configuration -------------------------------------------------- From 649a624c37f38ea0c13cda376b8aa61687535d1e Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 17:10:15 +0100 Subject: [PATCH 7/8] Install OpenMPI for sphinx-gallery example execution --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d6f052f..b84c08f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,7 +33,7 @@ jobs: - name: Install system dependencies run: | sudo apt-get update - sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended texlive-science dvipng cm-super libosmesa6-dev libgl1-mesa-dev + sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended texlive-science dvipng cm-super libosmesa6-dev libgl1-mesa-dev libopenmpi-dev openmpi-bin - name: Install uv uses: astral-sh/setup-uv@v4 From 0e6248f967de4ad9a7d1326443fb91507f587a56 Mon Sep 17 00:00:00 2001 From: Philip Korsager Nickel Date: Fri, 28 Nov 2025 17:20:13 +0100 Subject: [PATCH 8/8] Fix sphinx documentation warnings --- Experiments/01-kernels/README.rst | 4 ++-- Experiments/01-kernels/plot_kernels.py | 4 ++-- Experiments/04-validation/compute_validation.py | 5 ++++- docs/source/api_reference.rst | 10 +--------- 4 files changed, 9 insertions(+), 14 deletions(-) diff --git a/Experiments/01-kernels/README.rst b/Experiments/01-kernels/README.rst index a0f271e..cdb9e1a 100644 --- a/Experiments/01-kernels/README.rst +++ b/Experiments/01-kernels/README.rst @@ -1,5 +1,5 @@ -01 - Choise of Kernel: Numpy vs Numba -====================== +01 - Choice of Kernel: NumPy vs Numba +====================================== Description ----------- diff --git a/Experiments/01-kernels/plot_kernels.py b/Experiments/01-kernels/plot_kernels.py index 3dd1ecc..77aaf44 100644 --- a/Experiments/01-kernels/plot_kernels.py +++ b/Experiments/01-kernels/plot_kernels.py @@ -1,6 +1,6 @@ """ -Visualization of kernel experiments -=========================== +Visualization of Kernel Experiments +==================================== Comprehensive analysis and visualization of NumPy vs Numba kernel benchmarks. """ diff --git a/Experiments/04-validation/compute_validation.py b/Experiments/04-validation/compute_validation.py index 5360d08..4db0a78 100644 --- a/Experiments/04-validation/compute_validation.py +++ b/Experiments/04-validation/compute_validation.py @@ -1,5 +1,8 @@ """ -Solver Validation: Run solver across configurations and save results. +Solver Validation +================= + +Run solver across configurations and save results. """ from Poisson import run_solver, get_project_root diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst index e32bf9b..89f9eca 100644 --- a/docs/source/api_reference.rst +++ b/docs/source/api_reference.rst @@ -308,15 +308,7 @@ Computational Kernels ===================== The package provides two implementations of the Jacobi iteration kernel through the :mod:`Poisson.kernels` module. - -.. .. autosummary:: -.. :toctree: generated -.. -.. jacobi_step_numpy -.. jacobi_step_numba - -NumPy and Numba kernel implementations are available through the :class:`NumPyKernel` and :class:`NumbaKernel` classes. -See the :doc:`generated/Poisson.kernels` module documentation for details. +NumPy and Numba kernel implementations are available through the ``NumPyKernel`` and ``NumbaKernel`` classes. Problem Setup =============