Syntax to document cmake files, functions and macros

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Syntax to document cmake files, functions and macros

Olivier Croquette
Hello,

I have quite a few .cmake files that I want to document. They define
functions, macros, and variables, and I was wondering if there is any
standard or tooling to help.

Is there a complete specification of the syntax used in the CMake
distribution itself?

E.g.:

add_executable(<name> [WIN32] [MACOSX_BUNDLE]
                [EXCLUDE_FROM_ALL]
                [source1] [source2 ...])

add_definitions(-DFOO -DBAR ...)

add_custom_target(Name [ALL] [command1 [args1...]]
                   [COMMAND command2 [args2...] ...]
                   [DEPENDS depend depend depend ... ]
                   [BYPRODUCTS [files...]]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [VERBATIM] [USES_TERMINAL]
                   [COMMAND_EXPAND_LISTS]
                   [SOURCES src1 [src2...]])

It looks like the documentation is not completely consistent by the way,
for instance, the first argument of add_executable is <name>, and of
add_custom_target is Name, although is same situation, isn't it?


For functions and macros, I can reuse this syntax, is there anything
similar for documenting a file, or variables?

More generally, is there anything like Doxygen, Javadoc, both in terms
of syntax and tooling to generate documents from source code?

Olivier

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Syntax to document cmake files, functions and macros

Oleksii Vilchanskyi
On 12/24/18 12:01 PM, Olivier Croquette wrote:
> I have quite a few .cmake files that I want to document. They define
> functions, macros, and variables, and I was wondering if there is any
> standard or tooling to help.

Yes, see [1]. You can find concrete examples at [2].

[1]:
<https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#help>
[2]: <https://gitlab.kitware.com/cmake/cmake/tree/master/Modules>


--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Syntax to document cmake files, functions and macros

Marc Herbert
>
> On 24 Dec 2018, at 03:32, Oleksii Vilchanskyi <oleksii.vilchanskyi at gmail.com> wrote:
>
> On 12/24/18 12:01 PM, Olivier Croquette wrote:
>> I have quite a few .cmake files that I want to document. They define
>> functions, macros, and variables, and I was wondering if there is any
>> standard or tooling to help.
>
> Yes, see [1]. You can find concrete examples at [2].
>
> [1]:
> <https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#help>
> [2]: <https://gitlab.kitware.com/cmake/cmake/tree/master/Modules>

This is very promising, however:

https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#module-documentation

“ This manual is intended for reference by developers modifying the CMake source tree itself,
and by those authoring externally-maintained modules.
...
To document CMake module Modules/<module-name>.cmake,
modify Help/manual/cmake-modules.7.rst to reference the module in the toctree directive
...
Test the documentation formatting by running cmake --help-module <module-name>,
and also by enabling the SPHINX_HTML and SPHINX_MAN options to build the documentation."


So is there a relatively simple way to run the same tooling on any regular, non-module .cmake files
too and produce project-specific documentation?


--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Syntax to document cmake files, functions and macros

Torsten Robitzki


> Am 31.01.2019 um 19:55 schrieb Marc Herbert <[hidden email]>:
>
> So is there a relatively simple way to run the same tooling on any regular, non-module .cmake files
> too and produce project-specific documentation?

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.

regards,

Torsten

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Syntax to document cmake files, functions and macros

Marc Herbert
Le jeu. 31 janv. 2019 à 23:09, Torsten Robitzki <[hidden email]> 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

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake