[cmake-developers] documenting a CMake 'use' file

[Brad King]

On 12/18/2013 12:13 PM, Matthew Woehlke wrote:
> Does this mean one cannot e.g. use the CMake extensions and/or link to 
> topics in CMake's documentation (provided a known location of the same)?

Correct.  Sphinx does not support magic cross-referencing to external
documents.  Generating such links would require folding the document
into the build process of CMake itself.  Without that the links have
to be spelled out like any other external hyperlinks (http://...).

> I have a CMake module that is going to be provided by another project 
> (i.e. will not live in the CMake repository). It has RST documentation. 
> I would like to be able to generate HTML from that. How would you 
> recommend to do so?

So a file that comes in a project needs to be documented with the
documentation of the project.  Every project has that problem with
all its file types.  CMake now solves it for its own files in its
own source tree.  Other projects will have to do their own thing.
If they want to copy and re-use the infrastructure out of the
CMake source tree they are free to do so but will have to maintain
it themselves.  Another approach is to use sed+rst2html to extract
and process .rst markup from inside .cmake file comments.

-Brad