[Dune-devel] cmake and buildsystem documentation

[Christoph Grüninger]

Hi Simon,
thanks for your explanations!

> 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

I missed that, the source files are not part of CMake, they are only
available if people checkout CMake sources. This dependency would be bad.
Having it installed from pip sounds great for people using it. If the
files are not present, the Sphinx output would not work, right? I am
unsure whether we can accept that or not. I tend to accept it, it is
just a second dependency besides Sphinx to build the CMake documentation.

> 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.

It would be create to get these changes upstream into Sphinx. Not sure
how likely this would be.

> 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.

For people writing CMake documentation it is also needed, but this is
acceptable to me.

> 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.

The code is not obvious, would need more time to read it more thoroughly.

Bye
Christoph

-- 
Als wär es nix, leb' ich von [IT] und mach' nur, was ich lieb'
Lebe wie im Paradies, womit hab' ich das verdient?
Die Wahrheit ist: Hab' ich nicht, ich bin nur reicher beschenkt
Als jemand in einem armen Land mit dem gleichen Talent
[frei nach Tua von Die Orsons - Oioioiropa]