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

[Alexander Neundorf]

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