MarcelKoch · MarcelKoch · Mar 24, 2025 · Mar 24, 2025 · Mar 24, 2025 · Mar 25, 2025
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -11,20 +11,20 @@ build:
     - cmake
     - graphviz
   tools:
-    python: "3.11"
+    python: "3.12"
   jobs:
     pre_build:
-      - cmake -S . -B build \
-        -DGINKGO_BUILD_DOC=ON \
-        -DGINKGO_DOC_GENERATE_PDF=OFF \
-        -DGINKGO_BUILD_EXAMPLES=ON \
-        -DGINKGO_BUILD_TESTS=OFF \
-        -DGINKGO_BUILD_BENCHMARKS=OFF \
-        -DGINKGO_BUILD_REFERENCE=ON \
-        -DGINKGO_BUILD_OMP=OFF \
-        -DGINKGO_BUILD_CUDA=OFF \
-        -DGINKGO_BUILD_HIP=OFF \
-        -DGINKGO_BUILD_SYCL=OFF \
+      - cmake -S . -B build
+        -DGINKGO_BUILD_DOC=ON
+        -DGINKGO_DOC_GENERATE_PDF=OFF
+        -DGINKGO_BUILD_EXAMPLES=OFF
+        -DGINKGO_BUILD_TESTS=OFF
+        -DGINKGO_BUILD_BENCHMARKS=OFF
+        -DGINKGO_BUILD_REFERENCE=OFF
+        -DGINKGO_BUILD_OMP=OFF
+        -DGINKGO_BUILD_CUDA=OFF
+        -DGINKGO_BUILD_HIP=OFF
+        -DGINKGO_BUILD_SYCL=OFF
         -DGINKGO_BUILD_MPI=OFF
       - cmake --build build -t doxysphinx -- -j
 

diff --git a/README.md b/README.md
@@ -162,7 +162,7 @@ details.
 
 # Contributing to Ginkgo
 
-We are glad  that you would like to contribute to Ginkgo, and we are happy to help you with any questions you may have.
+We are glad that you would like to contribute to Ginkgo, and we are happy to help you with any questions you may have.
 
 If you are contributing for the first time, please add yourself to the list of external contributors with the following info
 

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -9,55 +9,27 @@ configure_file(
     @ONLY
 )
 
-# Creating symlinks to the sphinx sources in the build directory
+# Copy to the sphinx sources in the build directory
+# These have to be actual copies, since sphinx (or myst) can't
+# resolve (symbolic) links to files outside the sphinx source
+# directory
 file(
-    CREATE_LINK
-        ${CMAKE_CURRENT_SOURCE_DIR}/_static
-        ${CMAKE_CURRENT_BINARY_DIR}/_static
-    SYMBOLIC
-)
-file(
-    CREATE_LINK
-        ${CMAKE_CURRENT_SOURCE_DIR}/_templates
-        ${CMAKE_CURRENT_BINARY_DIR}/_templates
-    SYMBOLIC
-)
-file(
-    CREATE_LINK
-        ${CMAKE_CURRENT_SOURCE_DIR}/developer-guide
-        ${CMAKE_CURRENT_BINARY_DIR}/developer-guide
-    SYMBOLIC
-)
-file(
-    CREATE_LINK
-        ${CMAKE_CURRENT_SOURCE_DIR}/user-guide
-        ${CMAKE_CURRENT_BINARY_DIR}/user-guide
-    SYMBOLIC
-)
-file(
-    CREATE_LINK
-        ${CMAKE_CURRENT_SOURCE_DIR}/index.md
-        ${CMAKE_CURRENT_BINARY_DIR}/index.md
-    SYMBOLIC
+    COPY index.md _static _templates developer-guide user-guide
+    DESTINATION ${CMAKE_CURRENT_BINARY_DIR}
 )
 
 # Create symlinks for top-level files referenced by documentation
-file(MAKE_DIRECTORY ${Ginkgo_BINARY_DIR}/test/test_install/)
+# Here links are fine, since those files are not part of the documentation,
+# they are just referenced
 file(
     CREATE_LINK ${Ginkgo_SOURCE_DIR}/LICENSE ${Ginkgo_BINARY_DIR}/LICENSE
     SYMBOLIC
 )
-file(
-    CREATE_LINK
-        ${Ginkgo_SOURCE_DIR}/test/test_install/CMakeLists.txt
-        ${Ginkgo_BINARY_DIR}/test/test_install/CMakeLists.txt
-    SYMBOLIC
-)
 
 if(DEFINED ENV{READTHEDOCS_OUTPUT})
     set(GINKGO_SPHINX_BUILD_DIR $ENV{READTHEDOCS_OUTPUT}/html)
 else()
-    set(GINKGO_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/_build)
+    set(GINKGO_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/html)
 endif()
 
 add_custom_target(

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -3,14 +3,15 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os
+import datetime
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Ginkgo'
-copyright = '2024, The Ginkgo Authors'
+copyright = f'{datetime.date.today().year}, The Ginkgo Authors'
 author = 'The Ginkgo Authors'
-release = '1.9.0'
+release = '@Ginkgo_VERSION@'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
@@ -350,30 +350,9 @@ DISABLE_INDEX          = NO
 
 GENERATE_TREEVIEW      = NO
 
-# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
-# When MathJax is enabled you need to specify the location relative to the HTML
-# output directory using the MATHJAX_RELPATH option. The destination directory
-# should contain the MathJax.js script. For instance, if the mathjax directory
-# is located at the same level as the HTML output directory, then
-# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax
-# Content Delivery Network so you can quickly see the result without installing
-# MathJax. However, it is strongly recommended to install a local copy of
-# MathJax from https://www.mathjax.org before deployment. The default value is:
-# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2
-# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3
-# This tag requires that the tag USE_MATHJAX is set to YES.
-
-MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@2
+USE_MATHJAX = YES
+MATHJAX_VERSION = MathJax_3
+MATHJAX_FORMAT = chtml
 
 # When the SEARCHENGINE tag is enabled Doxygen will generate a search box for
 # the HTML output. The underlying search engine uses JavaScript and DHTML and

diff --git a/doc/doxygen/examples/examples.hpp.in b/doc/doxygen/examples/examples.hpp.in
@@ -230,6 +230,11 @@
  *       </td></tr>
  *
  *   <tr valign="top">
+ *       <td>@subpage distributed_multigrid_preconditioned_solver</td>
+ *       <td> Use a distributed solver to solve a 1D Laplace equation.
+ *       </td></tr>
+ *
+ *   <tr valign="top">
  *       <td>@subpage batched_solver</td>
  *       <td> Using and interfacing with a batched solver.
  *       </td></tr>
@@ -259,6 +264,11 @@
  *       <td> Use the FFT and iFFT implementations to solve Schrödinger's equation.
  *       </td></tr>
  *
+ *   <tr valign="top">
+ *       <td>@subpage file_config_solver</td>
+ *       <td> Use a solver from a config file in Ginkgo to solve a linear system.
+ *       </td></tr>
+ *
  * </table>
  *
  * <a name="topic"></a>
@@ -424,6 +434,7 @@
  *     <td> Distributed
  *     </td>
  *     <td>@ref distributed_solver
+ *         @ref distributed_multigrid_preconditioned_solver
  *     </td>
  *   </tr>
  * </table>

diff --git a/doc/doxygen/mainpage.md b/doc/doxygen/mainpage.md
@@ -2,12 +2,12 @@ This is the main page for the Ginkgo library API documentation.
 
 ## Topics
 
-The Ginkgo library can be grouped into modules which form the basic building blocks of Ginkgo. The topics can be summarized as follows:
+The Ginkgo library can be grouped into topics which form the basic building blocks of Ginkgo. The topics can be summarized as follows:
 
-*   @ref Executor : Where do you want your code to be executed ?
-*   @ref LinOp : What kind of operation do you want Ginkgo to perform ?
+*   @ref Executor : Where do you want your code to be executed?
+*   @ref LinOp : What kind of operation do you want Ginkgo to perform?
     * @ref solvers : Solve a linear system for a given matrix.
-    * @ref precond : Precondition a system for a solve. 
+    * @ref precond : Precondition a solver for a linear system.
     * @ref mat_formats : Perform a sparse matrix vector multiplication with a particular matrix format.
 *   @ref log : Monitor your code execution.
 *   @ref stop : Manage your iteration stopping criteria.
diff --git a/doc/doxygen/scripts/make_example.pl b/doc/doxygen/scripts/make_example.pl
@@ -92,9 +92,13 @@
 
 system $^X, "$cmake_source_dir/doc/doxygen/scripts/create_anchors", "$cmake_source_dir/examples/$example/doc/results.dox";
 
-print
-"<a name=\"PlainProg\"></a>
-<h1> The plain program</h1>
-\@include \"$example.cpp\"
- */
-";
+print "<a name=\"PlainProg\"></a>";
+print "<h1> The plain program</h1>\n";
+print " * \@code\n";
+open(my $prog, '<', "$example.cpp") or die "Can't open plain program $example.cpp";
+while(my $line = readline($prog)){
+    print " *    $line"
+}
+close $prog;
+print " * \@endcode\n";
+print "*/";
diff --git a/doc/user-guide/about-licensing.md b/doc/user-guide/about-licensing.md
@@ -84,10 +84,10 @@ benchmark suites. gtest is available under the following license:
 
 nlohmann-json is available under the following license:
 
-> MIT License 
-> 
+> MIT License
+>
 > Copyright (c) 2013-2022 Niels Lohmann
-> 
+>
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
 > in the Software without restriction, including without limitation the rights
@@ -97,7 +97,7 @@ nlohmann-json is available under the following license:
 >
 > The above copyright notice and this permission notice shall be included in all
 > copies or substantial portions of the Software.
-> 
+>
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -112,17 +112,17 @@ will be downloaded. doxygen-awesome-css is available under the following license
 > MIT License
 >
 > Copyright (c) 2021 - 2023 jothepro
-> 
+>
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
 > in the Software without restriction, including without limitation the rights
 > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 > copies of the Software, and to permit persons to whom the Software is
 > furnished to do so, subject to the following conditions:
-> 
+>
 > The above copyright notice and this permission notice shall be included in all
 > copies or substantial portions of the Software.
-> 
+>
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -144,7 +144,7 @@ also licensed the same as the deal.II library.
 > modify it under the terms of the GNU Lesser General Public License as published
 > by the Free Software Foundation; either version 2.1 of the License, or (at your
 > option) any later version.
-> 
+>
 > The full text of the GNU Lesser General Public
 > version 2.1 is available on the [deal.II repository
 > page](https://github.com/dealii/dealii/blob/master/LICENSE.md) or on the
@@ -230,18 +230,18 @@ For detecting the HWLOC library, we used a modified version of the FindHWLOC.cma
 __NOTE:__ Some of the options that pull additional software when compiling
 Ginkgo are ON by default, and have to be disabled manually to prevent
 third-party licensing. Refer to the [Installation section in
-install.md](install.md#building) for more details.
+install.md](install.md) for more details.
 
 
 When using testing with MPI switched on, the gtest-mpi-listener header only library is used for testing MPI functionality. The repository is licensed triple licensed under BSD-3, MIT and Apache 2.0. The License duplicated below. More details on the License and the library are [available on github](https://github.com/LLNL/gtest-mpi-listener)
 
 
 > Copyright 2005, Google Inc.  All rights reserved.
-> 
+>
 > Redistribution and use in source and binary forms, with or without
 > modification, are permitted provided that the following conditions are
 > met:
-> 
+>
 > * Redistributions of source code must retain the above copyright
 > notice, this list of conditions and the following disclaimer.
 > * Redistributions in binary form must reproduce the above
@@ -251,7 +251,7 @@ When using testing with MPI switched on, the gtest-mpi-listener header only libr
 > * Neither the name of Google Inc. nor the names of its
 > contributors may be used to endorse or promote products derived from
 > this software without specific prior written permission.
-> 
+>
 > THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 > "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 > LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

diff --git a/doc/user-guide/benchmarking.md b/doc/user-guide/benchmarking.md
@@ -229,8 +229,7 @@ The benchmark suite can take a number of configuration parameters. Benchmarks
 can be run only for `sparse matrix vector products (spmv)`, for full solvers
 (with or without preconditioners), or for preconditioners only when supported.
 The benchmark suite also allows to target a sub-part of the SuiteSparse matrix
-collection. For details, see the [available benchmark options](## 6: Available
-benchmark options). Here are the most important options:
+collection. For details, see the [available benchmark options](#7-available-benchmark-options). Here are the most important options:
 * `BENCHMARK={spmv, solver, preconditioner}` - allows to select the type of
     benchmark to be ran.
 * `EXECUTOR={reference,cuda,hip,omp,dpcpp}` - select the executor and platform

diff --git a/doc/user-guide/install.md b/doc/user-guide/install.md
@@ -26,7 +26,7 @@ Ginkgo adds the following additional switches to control what is being built:
     Enabling this flag increases the library size, but improves performance of
     mixed-precision kernels.
 *   `-DGINKGO_ENABLE_HALF={ON, OFF}` enable half precision support in Ginkgo, default is `ON`.
-    It is `OFF` when the compiler is MSVC or MSYS2 system. If compiling is done with the CUDA backend before CUDA 12.2, 
+    It is `OFF` when the compiler is MSVC or MSYS2 system. If compiling is done with the CUDA backend before CUDA 12.2,
     we only support half precision after compute capability 5.3. CUDA 12.2+ compilers waive the compute capbility limitation.
 *   `-DGINKGO_BUILD_TESTS={ON, OFF}` builds Ginkgo's tests
     (will download googletest), default is `ON`.
@@ -59,12 +59,8 @@ Ginkgo adds the following additional switches to control what is being built:
 *   `-DGINKGO_BUILD_HWLOC={ON, OFF}` builds Ginkgo with HWLOC. Default is `OFF`.
 *   `-DGINKGO_BUILD_DOC={ON, OFF}` creates an HTML version of Ginkgo's documentation
     from inline comments in the code. The default is `OFF`.
-*   `-DGINKGO_DOC_GENERATE_EXAMPLES={ON, OFF}` generates the documentation of examples
-     in Ginkgo. The default is `ON`.
 *   `-DGINKGO_DOC_GENERATE_PDF={ON, OFF}` generates a PDF version of Ginkgo's
     documentation from inline comments in the code. The default is `OFF`.
-*   `-DGINKGO_DOC_GENERATE_DEV={ON, OFF}` generates the developer version of
-    Ginkgo's documentation. The default is `OFF`.
 *   `-DGINKGO_WITH_CLANG_TIDY={ON, OFF}` makes Ginkgo call `clang-tidy` to find
     programming issues. The path can be manually controlled with the CMake
     variable `-DGINKGO_CLANG_TIDY_PATH=<path>`. The default is `OFF`.
@@ -249,7 +245,7 @@ user, e.g. when installing Ginkgo system-wide, it might be necessary to prefix
 the call with `sudo`.
 
 After the installation, CMake can find ginkgo with `find_package(Ginkgo)`.
-An example can be found in the [`test_install`](../../test/test_install/CMakeLists.txt).
+An example can be found in the [`test_install`](https://github.com/ginkgo-project/ginkgo/blob/develop/test/test_install/CMakeLists.txt).
 
 :::{toctree}
 :hidden: