Merge pull request #724 from sebproell/list-cmake-vars

List all our CMake variables in the documentation

Author: sebproell

doc/documentation/CMakeLists.txt

@@ -41,6 +41,10 @@ if(FOUR_C_BUILD_DOCUMENTATION)
     COMMAND
       cmake ${PROJECT_SOURCE_DIR} --list-presets >
       ${_sphinx_OUT_DIR}/reference_docs/4C-cmake-presets.txt
+    COMMAND
+      bash ${CMAKE_CURRENT_SOURCE_DIR}/scripts/extract_cmake_variables.sh
+      ${PROJECT_BINARY_DIR}/CMakeCache.txt >
+      ${_sphinx_OUT_DIR}/reference_docs/4C-cmake-variables.csv
     COMMAND
       ${SPHINX_EXECUTABLE} -W -n -q -b html # warnings are errors and be nit-picky
       -i "${CMAKE_CURRENT_SOURCE_DIR}/src" -i "${_sphinx_OUT_DIR}/reference_docs" -i

doc/documentation/scripts/extract_cmake_variables.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# This file is part of 4C multiphysics licensed under the
+# GNU Lesser General Public License v3.0 or later.
+#
+# See the LICENSE.md file in the top-level for license information.
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+# This script extracts CMake variables from the CMakeCache.txt file.
+CACHE_FILE=$1
+
+awk '
+BEGIN {
+  print "Variable,Type,Description"
+  doc = ""
+}
+/^\/\// {
+  line = $0
+  gsub("^//", "", line)
+  gsub(/^[ \t]+|[ \t]+$/, "", line)
+  doc = (doc == "") ? line : doc " " line
+  next
+}
+/^[^#].*:/ {
+  split($0, a, ":")
+  name = a[1]
+  split(a[2], t, "=")
+  type = t[1]
+  if (name ~ /^FOUR_C/ && type != "INTERNAL") {
+    gsub(/"/, "\"\"", doc)
+    printf "\"``%s``\",\"%s\",\"%s\"\n", name, type, doc
+  }
+  doc = ""  # reset for next block
+}
+' ${CACHE_FILE}

doc/documentation/src/developer_guide/developer_cmake.rst

@@ -1,7 +1,7 @@
-.. _cmakepresets:
+.. _developer_cmake:
 
-CMake presets
---------------
+CMake
+-----
 
 CMake presets are |FOURC|'s recommended way to configure and manage different configurations of |FOURC|.
 This small article will go through a few of them. The experts should also read the
@@ -70,14 +70,25 @@ Don't be overwhelmed by the options you could potentially set.
   optimizes the build setup for iterative development cycles.
 - We try to detect reasonable defaults for you internally.
 
+Reference of all CMake variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Over time you might realize that you want to turn on additional dependencies or features.
-To see which other options you can set, consult the console output of CMake or run `ccmake .` in the build folder.
-Alternatively, all options are also printed with their ``ON`` or ``OFF`` state whenever ``cmake`` runs.
+To see which other options you can set, consult the console output of CMake or run ``ccmake .`` in the build folder.
+Alternatively, many options are also printed with their ``ON`` or ``OFF`` state whenever ``cmake`` runs.
 
-**Remark:** Variables either start with the prefix `FOUR_C_` indicating that this variable only affects |FOURC| itself,
-or they start with `CMAKE_` indicating that the variable (potentially) affects all dependent projects in a way
+**Remark:** Variables either start with the prefix ``FOUR_C_`` indicating that this variable only affects |FOURC| itself,
+or they start with ``CMAKE_`` indicating that the variable (potentially) affects all dependent projects in a way
 specified directly in the CMake documentation.
 
+This is a list of all variables that are available to configure |FOURC|:
+
+.. csv-table::
+    :file: /4C-cmake-variables.csv
+    :header-rows: 1
+    :widths: 20, 20, 60
+
+
 Configuration from the IDE
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/documentation/src/installation/installation.rst

@@ -173,7 +173,7 @@ In a preset within this file, you should define a few options that are important
 - the build directory. It is good practice to indicate the value for ``CMAKE_BUILD_TYPE`` in the folder name, e.g. by
   ``"binaryDir": "<4C-basedir>/builds/release-build"`` (the folder name is completely up to you).
 
-More information about the cmake presets can be found :ref:`here <cmakepresets>`.
+More information about the cmake presets can be found :ref:`here <developer_cmake>`.
 
 
 .. note::