[cmake-developers] Improving CPack Documentation (and may be others as well)
Alexander Neundorf
neundorf at kde.org
Wed Jan 25 16:40:29 EST 2012
On Wednesday 25 January 2012, Eric Noulard wrote:
> 2012/1/25 Brad King <brad.king at kitware.com>:
> > On 1/24/2012 5:50 PM, Eric Noulard wrote:
> >> cmake --help-module CPackComponent
> >> or any other (untouched module)
> >> cmake --help-module FindQt4
> >>
> >> you'll see that the extra space are there as well.
> >> So yes there is too much space, but this is not due to
> >> my current proposal, it was there before.
> >> We can handle that separately.
> >
> > Agreed. Sorry, I forgot that this problem already existed.
> > It was created by the original module documentation extractor.
> > It inconsistently treats transitions from paragraph text to
> > preformatted text and back, giving the latter extra blank lines.
> > Now we can't fix it without changing the formatting of all the
> > existing documentation. (Perhaps the markup can help with that
> > later.)
> >
> >> I won't be doing this now I'd rather agree on the new markup
> >> feature first.
> >
> > The markup feature looks fine to me. The markup syntax adds
> > some information even for those reading the raw source.
>
> Yes and I forgot to mention that it has a extra feature compared
> to the current module doc parser.
>
> It does look for markup on the **whole** file unlike
> current module doc parser which only parse the header
> (at the beginning of the file).
>
> So with my proposal you can perfectly document a script in the middle
> of the file or as usual just in front of the concerned
> macro/function/var. This may be easier for doc maintenance because
> the function/macro would be closer to its doc.
>
> This could be further used for user script that could be
> documented this way as well.
>
> My idea for user script doc support may be to add an extra
> "cdoc" command that would be dedicated to documentation
> of script files:
>
> a) cdoc --help-command-list yourscript.cmake
> b) cdoc --help-variable-list yourscript.cmake
> c) cdoc --help yourscript.cmake
>
> may spit out:
> a) the doc for macro/function in the concerned script
> b) the doc for variables
> c) all doc
>
> this command may have more versatile option to include
> or exclude (cmake/ctest/cpack) doc and/or add some path
> where to parse all *.cmake files etc....
>
> An alternative would be to defined something like:
> CMAKE_USER_DOC_PATHS
> CPACK_USER_DOC_PATHS
> CTEST_USER_DOC_PATHS
cmake already supports CMAKE_MODULE_PATH for generating help, e.g. like this:
$ cmake -DCMAKE_MODULE_PATH=$HOME/src/kdelibs/cmake/modules/ --help-custom-
modules
This generates docs for all cmake files in CMAKE_MODULE_PATH.
--help-module also looks in CMAKE_MODULE_PATH.
I'm not sure it needs a new variable.
Alex
More information about the cmake-developers
mailing list