[cmake-developers] cmake --help-custom-modules compatibility

[Brad King]

On 01/08/2014 12:00 PM, Matthew Woehlke wrote:
> Since you mentioned it, I was wondering if this is related to a feature 
> I was asking about, but I don't understand how it works; it seems to 
> only ever generate a short boilerplate text.
> 
> Is this meant to take a CMake module that is not part of the CMake 
> distribution and extract and format the documentation from the same? 

The old documentation system exposed this feature through the old
--help-custom-modules option.  The new documentation system does not.
This commit is about making old builds not totally break.

> Because that is a feature I really wish CMake 3.0 would provide. (I know 
> you (Brad) previously mentioned that you don't want to in order to avoid 
> committing to any sort of compatibility guarantees with respect to the 
> same. But it still seems to me that such decision makes it unnecessarily 
> hard for third parties to provide documented CMake modules.)

That discussion left off here:

 http://thread.gmane.org/gmane.comp.programming.tools.cmake.devel/8727/focus=8943

and should continue there rather than here.  In summary I pointed out
that there is no clean way to cross-reference CMake's documentation
from external modules except by spelling out hyperlinks by hand.
I also suggested an approach to document external modules without using
CMake's Sphinx configuration.

Anyone could fork CMake's Utilities/Sphinx infrastructure and provide
it as a separate distribution with support and compatibility guarantees.
I just do not want to provide it with CMake and constrain CMake's own
documentation from evolving just to support external documents.  The
compatibility issue in this thread is a perfect example of why.

-Brad