[cmake-developers] cmake --help-custom-modules compatibility
brad.king at kitware.com
Wed Jan 8 12:57:22 EST 2014
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:
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.
More information about the cmake-developers