<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
</head>
<body dir="ltr">
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Hi Simon.</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Sounds good to me especially since I don't understand what the drawbacks are (if there are any).</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Best</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Andreas<br>
</div>
<div id="appendonsend"></div>
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" style="font-size:11pt" color="#000000"><b>From:</b> Dune-devel <dune-devel-bounces@lists.dune-project.org> on behalf of Simon Praetorius <simon.praetorius@tu-dresden.de><br>
<b>Sent:</b> 16 May 2021 18:27<br>
<b>To:</b> dune-devel@lists.dune-project.org <dune-devel@lists.dune-project.org><br>
<b>Subject:</b> [Dune-devel] cmake and buildsystem documentation</font>
<div> </div>
</div>
<div class="BodyFragment"><font size="2"><span style="font-size:11pt;">
<div class="PlainText">Hi everyone,<br>
<br>
In the last months me and others have updated several cmake files, e.g., <br>
Find<package>.cmake package modules. During this update, I have changed <br>
the way cmake code is documented. I followed the recommendation given by <br>
cmake developers in<br>
<br>
<a href="https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#id6">https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#id6</a><br>
<br>
Since cmake 3.x multi-line comments are supported, starting with<br>
<br>
#[===========================[.rst:<br>
...<br>
comments<br>
...<br>
#]===========================]<br>
<br>
This makes long cmake documentation more readable (in my opinion). <br>
Additionally, I used code blocks to document cmake functions.<br>
<br>
Recently, I discovered that this way of documentation is not covered by <br>
the way in Dune the documentation is extracted from .cmake files. This <br>
is done manually by a python script, since there is no available tool <br>
from cmake for this task. Files are parsed and then some special tags <br>
are found representing function, variable or parameter documentations. <br>
In order to support multi-line comments this extraction needs to be <br>
extended.<br>
<br>
While searching the web for ways how to do this extraction and <br>
documentation generation in a more standardized way, e.g., by public <br>
available tools, I have found at least the sphinx "domain" extension to <br>
represent cmake commands and variables. This is available from<br>
<br>
<a href="https://pypi.org/project/sphinxcontrib-moderncmakedomain/">https://pypi.org/project/sphinxcontrib-moderncmakedomain/</a><br>
<br>
Thus, we just need to write the documentation in a cmake compatible way, <br>
put into an multi-line comment block at the beginning of the file and <br>
then run sphinx on the generated .rst files. I have written the <br>
corresponding extension in the file `extract_cmake_Data.py` in the MR<br>
<br>
<a href="https://gitlab.dune-project.org/core/dune-common/-/merge_requests/957">https://gitlab.dune-project.org/core/dune-common/-/merge_requests/957</a>
<br>
(branch feature/separate-cmake-files)<br>
<br>
In my opinion, the generated documentation looks nice in HTML format and <br>
additionally, the documentation inside cmake source files are better <br>
readable.<br>
<br>
What is your opinion on this? Should we support this way of <br>
documentation (in addition to the old way)?<br>
<br>
Best regards,<br>
Simon<br>
<br>
-- <br>
Dr. Simon Praetorius<br>
Technische Universität Dresden<br>
Institute of Scientific Computing<br>
phone: +49 351 463-34432<br>
mail: simon.praetorius@tu-dresden.de<br>
<br>
<br>
_______________________________________________<br>
Dune-devel mailing list<br>
Dune-devel@lists.dune-project.org<br>
<a href="https://lists.dune-project.org/mailman/listinfo/dune-devel">https://lists.dune-project.org/mailman/listinfo/dune-devel</a></div>
</span></font></div>
</body>
</html>