diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 8ecd9e3..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
@@ -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'
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
 =============
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 --------------------------------------------------
 
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__":