[Dune-devel] cmake and buildsystem documentation

[Simon Praetorius]

Hi everyone,

In the last months me and others have updated several cmake files, e.g., 
Find<package>.cmake package modules. During this update, I have changed 
the way cmake code is documented. I followed the recommendation given by 
cmake developers in

https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#id6

Since cmake 3.x multi-line comments are supported, starting with

#[===========================[.rst:
...
comments
...
#]===========================]

This makes long cmake documentation more readable (in my opinion). 
Additionally, I used code blocks to document cmake functions.

Recently, I discovered that this way of documentation is not covered by 
the way in Dune the documentation is extracted from .cmake files. This 
is done manually by a python script, since there is no available tool 
from cmake for this task. Files are parsed and then some special tags 
are found representing function, variable or parameter documentations. 
In order to support multi-line comments this extraction needs to be 
extended.

While searching the web for ways how to do this extraction and 
documentation generation in a more standardized way, e.g., by public 
available tools, I have found at least the sphinx "domain" extension to 
represent cmake commands and variables. This is available from

   https://pypi.org/project/sphinxcontrib-moderncmakedomain/

Thus, we just need to write the documentation in a cmake compatible way, 
put into an multi-line comment block at the beginning of the file and 
then run sphinx on the generated .rst files. I have written the 
corresponding extension in the file `extract_cmake_Data.py` in the MR

https://gitlab.dune-project.org/core/dune-common/-/merge_requests/957 
(branch feature/separate-cmake-files)

In my opinion, the generated documentation looks nice in HTML format and 
additionally, the documentation inside cmake source files are better 
readable.

What is your opinion on this? Should we support this way of 
documentation (in addition to the old way)?

Best regards,
Simon

-- 
Dr. Simon Praetorius
Technische Universität Dresden
Institute of Scientific Computing
phone: +49 351 463-34432
mail: simon.praetorius@​tu-dresden.de