[CMake] Syntax to document cmake files, functions and macros

[Marc Herbert]

Le jeu. 31 janv. 2019 à 23:09, Torsten Robitzki <Torsten at robitzki.de> a
écrit :

>
> We are working on a larger CMake project and we use Sphinx. We use
> sphinxcontrib.moderncmakedomain as extension, which adds CMake syntax
> highlighting and sphinx.ext.intersphinx to allow us, to refer to the
> original CMake documentation.
>

Thanks Torsten, that was really useful. I was reluctant to spend time
understanding the project's build system (cause it has... no documentation
outside the source ;-) but I'm glad I did, now it's mostly just:

pip3 install --user sphinxcontrib-moderncmakedomain

.. cmake-module:: does/not/have/to/be/a/module.cmake

More details at https://pypi.org/project/sphinxcontrib-moderncmakedomain/

I didn't try sphinx.ext.intersphinx.

I'm still a bit confused about Kitware's official stance about this sphinx
extension though. Quoting:

- https://pypi.org/project/sphinxcontrib-moderncmakedomain/
"I will do my best to keep this module in sync with the one that Kitware
uses themselves."
apparently a selection from:
https://github.com/Kitware/CMake/tree/master/Utilities/Sphinx/
- https://cmake.org/cmake/help/v3.13/manual/cmake-developer.7.html
This manual is intended for reference by developers modifying the CMake
source tree itself, and by those authoring externally-maintained modules.

So while sphinxcontrib-moderncmakedomain seems to just work on any .cmake
file, it's not officially supported beyond modules and not distributed for
all users in pre-built packages?

There are (too) many developers who don't want to go anywhere near their
own build system. There are even more who don't want to go near a build
system with an indirection like CMake. Something like
sphinxcontrib-moderncmakedomain would really help there IMHO.

Marc
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://cmake.org/pipermail/cmake/attachments/20190211/b7c4447d/attachment.html>