[Dune-devel] cmake and buildsystem documentation

[Dedner, Andreas]

Hi Simon.
Sounds good to me especially since I don't understand what the drawbacks are (if there are any).
Best
Andreas
________________________________
From: Dune-devel <dune-devel-bounces at lists.dune-project.org> on behalf of Simon Praetorius <simon.praetorius at tu-dresden.de>
Sent: 16 May 2021 18:27
To: dune-devel at lists.dune-project.org <dune-devel at lists.dune-project.org>
Subject: [Dune-devel] cmake and buildsystem documentation

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


_______________________________________________
Dune-devel mailing list
Dune-devel at lists.dune-project.org
https://lists.dune-project.org/mailman/listinfo/dune-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.dune-project.org/pipermail/dune-devel/attachments/20210517/de67340e/attachment.htm>