Add a doc-only module for CMake builtin commands and variables

We aim to document the entire relevant user API. Some functions
from CMake are not worth wrapping, so we need to add them to our
documentation.

cmake/modules/CMakeBuiltinFunctionsDocumentation.cmake

+# This modules contains only documentation for CMake builtins.
+# This is necessary to have an complete API documentation.
+#
+# .. cmake_function:: add_subdirectory
+#
+#    .. cmake_param:: dir
+#       :single:
+#       :positional:
+#       :required:
+#
+#       The :code:`CMakeLists.txt` file from this subdirectory
+#       will be executed next.
+#
+#    .. cmake_param:: EXCLUDE_FROM_ALL
+#       :option:
+#
+#       Whether targets added in this subdirectory should be built
+#       during :code:`make all`.
+#
+#    This is a cmake builtin command.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-command add_subdirectory
+#
+# .. cmake_function:: install
+#
+#    Define installation rules to customize the behaviour of :code:`make install`.
+#
+#    This is a cmake builtin command.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-command install
+#
+# .. cmake_function:: add_executable
+#
+#    Adds an executable to the project.
+#
+#    This is a cmake builtin command.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-command add_executable
+#
+# .. cmake_function:: add_test
+#
+#    Adds a test to the testing suite.
+#
+#    This is a cmake builtin command.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-command add_test
+#
+# .. cmake_variable:: CMAKE_<LANG>_COMPILER
+#
+#    Set the compiler for the language LANG.
+#    LANG is in our case out of C, CXX.
+#
+#    This is a cmake builtin variable.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-variable CMAKE_\<LANG\>_COMPILER
+#
+# .. cmake_variable:: CMAKE_<LANG>_FLAGS
+#
+#    Set the compile flags for the language LANG.
+#    LANG is in our case out of C, CXX.
+#
+#    This is a cmake builtin variable.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-variable CMAKE_\<LANG\>_FLAGS
+#
+# .. cmake_function:: find_package
+#
+#    Look for an external package.
+#
+#    This is a cmake builtin command.
+#    For detailed information, check the cmake documentation:
+#
+#    .. code-block: bash
+#
+#       cmake --help-command find_package
+#

doc/buildsystem/dune-common.rst

@@ -227,7 +227,7 @@ How do I change my compiler and compiler flags?
 
 In general, there are multiple ways to do this:
 
-* Setting the CMake variables :ref:`CMAKE_C_COMPILER` and :ref:`CMAKE_CXX_COMPILER` resp. from the opts file
+* Setting the CMake variables :ref:`CMAKE_<LANG>_COMPILER` (with :code:`LANG` being :code:`C` or :code:`CXX`) from the opts file
 * Setting those variables within the project with the :code:`set` command
 * Setting the environment variables :code:`CC`, :code:`CXX` etc.
 
@@ -236,7 +236,7 @@ directories. For some CMake versions, there is a known CMake bug, that requires
 to your compiler, but Dune will issue a warning, if you violate that.
 
 You can modify your default compiler flags by setting the variables
-:ref:`CMAKE_C_FLAGS` and :ref:`CMAKE_CXX_FLAGS` in your opts file.
+:ref:`CMAKE_<LANG>_FLAGS` in your opts file (again with :code:`LANG` being :code:`C` or :code:`CXX`).
 
 .. _symlink: