[cmake-developers] Improving CPack Documentation (and may be others as well)

Eric Noulard eric.noulard at gmail.com
Mon Jan 2 19:43:36 EST 2012


Hi All,

I try to push forward the feature request:
http://public.kitware.com/Bug/view.php?id=10067

I have something working for
cpack --help-command
and
cpack --help-variables

for which the documentation are automatically extracted from concerned
*.cmake files,
namely;

CPack.cmake
CPackComponent.cmake
CPackRPM.cmake
CPackDeb.cmake

The needed modifications are minor, you "just" have to add extra markup, like:
##variable
#   CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
#   not including the extension. For example, cmake-2.6.1-Linux-i686.
##end

and then you can ask
cpack --help-variable CPACK_PACKAGE_FILE_NAME

and you get the corresponding doc.
This is far less painful than adding extra static string vars in the C++ code
with the drawback that some files are parsed at run time
(just like when you do cmake --help-module CPack).

The great advantage being that the technique could be used to document
macros, functions and variables directly in CMake script files.

Currently the *.cmake files which are parsed are specified directly in
cpack.cxx code but we can easily design a scheme which would make
this more flexible.
The very same technique could then be used for CMake or CTest and even
for user-written CMake scripts as well.

My proposal does not solve the problem of having more markup
(like bold, cross-reference/link etc...) but is ease the creation
of doc structure by creating cmDocumentationEntry
[(name, brief, full description) string triplet] from the new markup.

Anybody have some time to try this?
I'd like to have some feedback before going on.

The branch is stage/ImproveCPackDoc.


-- 
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org



More information about the cmake-developers mailing list