[Dune-devel] cmake and buildsystem documentation

[Simon Praetorius]

I've just started to dive into this. Have not yet understood everything 
completely:

1.) This python package just provides two files from the cmake 
repository, that can easily be installed using pip, so if we do not want 
to get a dependency on the full cmake source package, this would be a 
minimal solution

2.) `sphinxcontrib-cmakedomain` is just another implementation of a 
Sphinx extension to understand cmake documentation tokens. It is 
outdated, though.

3.) I just wanted to find a way to document using the new multi-line 
comment blocks and to use the standard cmake documentation statements. 
This way we could import other cmake files and get the documentation 
included directly. I'm still experimenting, though. Maybe, if the 
license allows this, we could just include the two python files from 
cmake directly in our repository. Otherwise, this cmake documentation 
generation is purely optional and just used to generate online 
documentation files. It is thus only needed in one of our ci docker 
images and there we could easily add this additional dependency, since 
we added multiple other python packages recently as well.

I'm not yet sure how everything works. It seems that there is a python 
script provided as sphinx extension that would allow to parse the cmake 
files directly. Then we do not need to first extract the documentation 
manually into an .rst file and then run sphinx on this.

If someone is interested to look into this as well, I would appreciate 
the help.

Best,
Simon

Am 19.05.21 um 21:09 schrieb Christoph Grüninger:
> Hi Simon,
> I tried to understand the topic. Can help me?
>
> 1) https://pypi.org/project/sphinxcontrib-moderncmakedomain/ states:
>    "This is taken directly from the Kitware git repository's Utilities
> directory."
> Why should anybody maintain a copy of CMake's utility folder? Is it not
> possible to use the file from there?
>
> 2) Further:
>     "The original sphinxcontrib-cmakedomain has not been touched in quite
> some and as a result it wildly out of date."
> How is this repository related?
>
> 3) I welcome the general idea for having a nicer looking / better
> accessible documentation. But can it still be build without the newly
> introduced external dependency?
>
> Bye
> Christoph
>
> _______________________________________________
> Dune-devel mailing list
> Dune-devel at lists.dune-project.org
> https://lists.dune-project.org/mailman/listinfo/dune-devel

-- 
Dr. Simon Praetorius
Technische Universität Dresden
Institute of Scientific Computing
phone: +49 351 463-34432
mail: simon.praetorius at tu-dresden.de
web: https://tu-dresden.de/mn/math/wir/das-institut/beschaeftigte/simon-praetorius