docs fix

.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
@@ -49,8 +49,8 @@ jobs:
       - name: Build Sphinx docs
         env:
           PYVISTA_OFF_SCREEN: "true"
-          PYTHONPATH: "${{ github.workspace }}"
-        run: uv run python main.py --docs
+          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'

Experiments/01-kernels/README.rst

@@ -1,5 +1,5 @@
-01 - Choise of Kernel: Numpy vs Numba 
-======================
+01 - Choice of Kernel: NumPy vs Numba
+======================================
 
 Description
 -----------

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.
 """

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

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
 =============

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 --------------------------------------------------
 

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__":