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

[Marc Herbert]

Le jeu. 31 janv. 2019 à 23:09, Torsten Robitzki  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

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

[Torsten Robitzki]

> Am 31.01.2019 um 19:55 schrieb Marc Herbert :
> 
> 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


signature.asc
Description: Message signed with OpenPGP
-- 

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

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

[Marc Herbert]

> 
> On 24 Dec 2018, at 03:32, Oleksii Vilchanskyi  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]:
> 
> [2]: 

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

Re: [CMake] 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]:

[2]: 



signature.asc
Description: OpenPGP digital signature
-- 

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

[CMake] 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( [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 , 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