gimli-org · florian-wagner · Mar 18, 2026
diff --git a/doc/BUILD_LINUX.md b/doc/BUILD_LINUX.md
@@ -9,22 +9,22 @@ also local for all platforms.
 Prepare workspace:
 
 ```bash
-    mkdir -p gimli
-    git clone https://github.com/gimli-org/gimli.git
-    # optionally change to the development branch
-    git checkout dev
+mkdir -p gimli
+git clone https://github.com/gimli-org/gimli.git
+# optionally change to the development branch
+git checkout dev
 ```
 
 Running workflow:
 
 ```bash
-    bash gimli/.workflow.sh install
+bash gimli/.workflow.sh install
 ```
 
 The workflow have several targets which you might try:
 
 ```bash
-    bash gimli/.workflow.sh help
+bash gimli/.workflow.sh help
 ```
 
 If something goes wrong you can try the manual compilation.
@@ -38,34 +38,33 @@ First we need to create a root directory for our installation,
 e.g., ``$HOME/src/gimli`` and get the source code:
 
 ```bash
-    mkdir -p gimli
-    cd gimli
-    git clone https://github.com/gimli-org/gimli.git
-    # optionally change to the development branch
-    git checkout dev
-    # create a virtual environment for pyGIMLi, this can be at any place with any name
-    # if you want easy VScode support consider gimli/.venv
-    deactivate # in case there is another venv active
-    python -m venv venv-build --prompt=gimli-build
-    # activate the venv
-    source venv-build/bin/activate
-    # update pip is always a good idea
-    python -m pip install -U pip
-    # install gimli as editable with its dependencies into to venv
-    pip install -e ./gimli/[build]
+mkdir -p gimli
+cd gimli
+git clone https://github.com/gimli-org/gimli.git
+# optionally change to the development branch
+git checkout dev
+# create a virtual environment for pyGIMLi, this can be at any place with any name
+# if you want easy VScode support consider gimli/.venv
+deactivate # in case there is another venv active
+python -m venv venv-build --prompt=gimli-build
+# activate the venv
+source venv-build/bin/activate
+# update pip is always a good idea
+python -m pip install -U pip
+# install gimli as editable with its dependencies into to venv
+pip install -e ./gimli/[build]
 ```
 
 We need to compile the C++ part of pyGIMLi, which is currently done with cmake and not with the pip internal build system.
 We recommend an out of source build:
 
 ```bash
-
-    mkdir -p build
-    cd build
-    cmake ../gimli
-    make -j 4 gimli
-    make pygimli J=4
-    cd ..
+mkdir -p build
+cd build
+cmake ../gimli
+make -j 4 gimli
+make pygimli J=4
+cd ..
 ```
 
 There is no more need to change the `PATH` or `LD_LIBRARY_PATH`.
@@ -76,8 +75,8 @@ source tree which is already editable known to the venv,
 so you can test the pygimli build with:
 
 ```bash
-    python -c 'import pygimli as pg; pg.version()'
-    python -c 'import pygimli as pg; print(pg.Report())'
+python -c 'import pygimli as pg; pg.version()'
+python -c 'import pygimli as pg; print(pg.Report())'
 ```
 
 Note, if you test like this, ensure there is no actual path with a name
@@ -90,20 +89,20 @@ but just pulling the latest changes from git.
 If you end the terminal session you can reactivate the venv with:
 
 ```bash
-    source venv-build/bin/activate
+source venv-build/bin/activate
 ```
 
 ## Example Installation on Ubuntu
 
 Last try on Ubuntu 22.04.03 (23-11-14)
 
 ```bash
-    sudo apt-get install build-essential g++ subversion git cmake \
-                 python3-dev python3-matplotlib python3-numpy python3-pyqt5 \
-                 python3-scipy libboost-all-dev libedit-dev \
-                 libsuitesparse-dev libopenblas-openmp-dev libumfpack5 \
-                 libomp-dev doxygen \
-                 libcppunit-dev clang
+sudo apt-get install build-essential g++ subversion git cmake \
+            python3-dev python3-matplotlib python3-numpy python3-pyqt5 \
+            python3-scipy libboost-all-dev libedit-dev \
+            libsuitesparse-dev libopenblas-openmp-dev libumfpack5 \
+            libomp-dev doxygen \
+            libcppunit-dev clang
 ```
 
 Rest see above.

diff --git a/doc/BUILD_MAC.md b/doc/BUILD_MAC.md
@@ -1,57 +1,55 @@
 (build_mac)=
 # Building on MAC OSX
 
-The current working solution is based on `this discussion on GitHub
-<https://github.com/gimli-org/gimli/discussions/603>`_.  Many thanks to Robin
+The current working solution is based on [this discussion on GitHub](https://github.com/gimli-org/gimli/discussions/603). Many thanks to Robin
 Thibaut!
 
 ```bash
+# Install Homebrew
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 
-    # Install Homebrew
-    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+# Install dependencies via brew
+brew install cmake
+brew install wget
+brew install mercurial
 
-    # Install dependencies via brew
-    brew install cmake
-    brew install wget
-    brew install mercurial
+# Install Miniforge
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+bash Miniforge3-$(uname)-$(uname -m).sh
 
-    # Install Miniforge
-    curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
-    bash Miniforge3-$(uname)-$(uname -m).sh
+conda create -n pygimli_env python
+conda activate pygimli_env
+conda install -c conda-forge boost numpy scipy matplotlib openblas suitesparse
 
-    conda create -n pygimli_env python
-    conda activate pygimli_env
-    conda install -c conda-forge boost numpy scipy matplotlib openblas suitesparse
+# Clone the pygimli repository
+git clone https://github.com/gimli-org/gimli.git source
+mkdir build
+cd build
 
-    # Clone the pygimli repository
-    git clone https://github.com/gimli-org/gimli.git source
-    mkdir build
-    cd build
+PYTHON_EXEC=$(which python3)
+PYTHON_INC=$(python3 -c 'import sysconfig; print(sysconfig.get_path("include"))')
+PYTHON_LIB=$(python3-config --configdir)
 
-    PYTHON_EXEC=$(which python3)
-    PYTHON_INC=$(python3 -c 'import sysconfig; print(sysconfig.get_path("include"))')
-    PYTHON_LIB=$(python3-config --configdir)
+export CPLUS_INCLUDE_PATH=$PYTHON_INC
 
-    export CPLUS_INCLUDE_PATH=$PYTHON_INC
-
-    cmake -DPYTHON_EXECUTABLE=$PYTHON_EXEC -DPYTHON_LIBRARY=$PYTHON_LIB -DPYTHON_INCLUDE_DIR=$PYTHON_INC ../source
-    make -j 8
-    make pygimli J=8
+cmake -DPYTHON_EXECUTABLE=$PYTHON_EXEC -DPYTHON_LIBRARY=$PYTHON_LIB -DPYTHON_INCLUDE_DIR=$PYTHON_INC ../source
+make -j 8
+make pygimli J=8
 ```
 
 ## Troubleshooting
 
 If you encounter problems, you may have to specify some paths manually, e.g.:
 
 ```bash
-    cmake -DPYTHON_EXECUTABLE=$PYTHON_EXEC -DPYTHON_LIBRARY=$PYTHON_LIB
-          -DPYTHON_INCLUDE_DIR=$PYTHON_INC \
-          -DUMFPACK_LIBRARIES=~/minforge3/base/lib/libumfpack.dylib \
-          -DUMFPACK_INCLUDES=~/minforge3/base/include \
-          -DCHOLMOD_LIBRARIES=~/minforge3/base/lib/libcholmod.dylib \
-          -DCHOLMOD_INCLUDE_DIRS=~/minforge3/base/include \
-          -DBLAS_openblas_LIBRARY=~/minforge3/base/lib/libopenblas.dylib \
-          -DOpenBLAS_INCLUDE_DIR=~/minforge3/base/include \
-          -DBoost_PYTHON_LIBRARY=~/minforge3/base/lib/libboost_python310.dylib \
-          ../source
+cmake -DPYTHON_EXECUTABLE=$PYTHON_EXEC -DPYTHON_LIBRARY=$PYTHON_LIB
+    -DPYTHON_INCLUDE_DIR=$PYTHON_INC \
+    -DUMFPACK_LIBRARIES=~/minforge3/base/lib/libumfpack.dylib \
+    -DUMFPACK_INCLUDES=~/minforge3/base/include \
+    -DCHOLMOD_LIBRARIES=~/minforge3/base/lib/libcholmod.dylib \
+    -DCHOLMOD_INCLUDE_DIRS=~/minforge3/base/include \
+    -DBLAS_openblas_LIBRARY=~/minforge3/base/lib/libopenblas.dylib \
+    -DOpenBLAS_INCLUDE_DIR=~/minforge3/base/include \
+    -DBoost_PYTHON_LIBRARY=~/minforge3/base/lib/libboost_python310.dylib \
+    ../source
 ```
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -91,7 +91,7 @@ add_custom_target(sphinxhtml ALL
      WORKING_DIRECTORY
         ${SPHINX_BUILD_DIR}/doc
      COMMAND
-        sphinx-build -M html ./ "${SPHINX_BUILD_DIR}" --jobs=auto
+        sphinx-build -M html ./ "${SPHINX_BUILD_DIR}" --jobs=auto -b dirhtml
      COMMENT
          "Building HTML documentation with sphinx"
      DEPENDS
@@ -102,7 +102,7 @@ add_custom_target(sphinxhtml-NG ALL
      WORKING_DIRECTORY
         ${SPHINX_BUILD_DIR}/doc
      COMMAND
-        sphinx-build -M html ./ "${SPHINX_BUILD_DIR}" -D plot_gallery=0 --jobs=auto
+        sphinx-build -M html ./ "${SPHINX_BUILD_DIR}" -D plot_gallery=0 --jobs=auto -b dirhtml
      COMMENT
          "Building HTML documentation with sphinx"
      DEPENDS

diff --git a/doc/Makefile b/doc/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = --jobs auto -b dirhtml
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = ./
 BUILDDIR      = _build
@@ -41,12 +41,12 @@ api:
 	cp -f pygimliapi/physics_overwrite pygimliapi/_generated/pygimli.physics.rst
 
 html-nogallery: api
-	$(SPHINXBUILD) -D plot_gallery=0 -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -D plot_gallery=0 "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@echo
 	@echo "Build finished without gallery. The HTML pages are in $(BUILDDIR)."
 
 html: api
-	$(SPHINXBUILD) -v -D abort_on_example_error=True -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -v -D abort_on_example_error=True "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
 

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -6,8 +6,11 @@
 <h1 class="display-5">
   pyGIMLi is an open-source library for multi-method modelling and inversion in geophysics.
 </h1>
-<a class="btn btn-primary btn-lg mt-2" href="about.html">
-  Learn more
+<a class="btn btn-primary btn-lg mt-2" href="{{pathto('about')}}">
+  <i class="fas fa-book me-1"></i> Learn more
+</a>
+<a class="btn btn-success btn-lg mt-2 ms-2 text-white" href="{{pathto('user-guide/getting-started/index')}}">
+  <i class="fas fa-rocket me-1"></i> Getting started
 </a>
 
 <h1 class="mt-5">Showcase
@@ -84,7 +87,7 @@ <h1 class="mt-5">Get pyGIMLi.
   </small>
 </h1>
 pyGIMLi works on Windows, various Linux distributions and Mac OS. See the <a
-  href="installation.html">installation section</a> for more details on how to install the binaries or build pyGIMLi from the source code.
+  href="{{pathto('installation')}}">installation section</a> for more details.
 <h1 class="mt-5">Get started.
   <small class="text-muted">
     Check out the tutorials.