[cmake-developers] cmake --help-custom-modules compatibility (was: RST and documentation)

[Brad King]

On 11/18/2013 02:56 PM, Stephen Kelly wrote:
> We've had a while now to get used to the new docs system. Mostly I like it, 
> though I haven't really looked much into what rst offers.

This is really the start of several threads so I will branch out now.

> 2) Compatibility
> KDE relied on --help-custom-modules for creating a man page of the kde cmake 
> modules. That does not work with CMake 3.0.0:
> 
>  http://quickgit.kde.org/?p=kdelibs.git&a=commitdiff&h=804d35394c366
> 
> I am left wondering why it would be difficult to process the existing (and 
> very simple) markup in custom modules and generate rst on the fly for output 
> from --help-module MyCustomModule and similar. Is there a reason not to 
> restore compatibility like that? Otherwise any distro which upgrades to 
> cmake 3 will lose those man pages in the KDE case, and probably similar in 
> other cases. 
> 
> I think it would be best to avoid situations like distros packaging cmake 
> 2.8 and cmake 3.0, possibly renaming executables etc etc so that KDE4 and 
> other packages can continue to rely on cmake 2.8. Restoring and keeping 
> compatibility with issues like this would be important to prevent that.

The conversion topic was massive as it was and I didn't want to handle
this.  I didn't know it was used for anything except local command-line
help convenience.  The old help infrastructure was certainly not ever
intended for invocation in project build rules.

Note that all the --help-* options dropped support for man-page-formatted
output too:

 $ bin/cmake --help-modules cmake-modules.1
 Warning: Man help format no longer supported

I do not want to restore this behavior in general, but if you want to work
on restoring the old --help-custom-modules behavior specifically for KDE's
use case then please do so.  It should be a bare-minimum implementation
that extracts the old module documentation comment format and directly
produces manual page content.  It should work only when invoked as
"--help-custom-modules some-man-page.1".  That should restore support for
building existing KDE release man pages.  It should come with runtime
and documentation warnings about not using the interface in new code.

I do not want to try to expose and support a public interface to CMake's
internal Sphinx configuration, Sphinx extensions, and .rst module comment
scanning.  That will again limit our ability to refactor in the future.
If projects provide their own CMake modules they should do their own
thing to generate documentation for them.

-Brad