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

[Matthew Woehlke]

On 2013-12-18 11:52, Brad King wrote:
> On 12/10/2013 04:57 PM, Matthew Woehlke wrote:
>> Thanks. Are there any guidelines on documenting the parameters of CMake
>> functions/macros? I didn't see that in the mentioned document.
>
> No convention has been established so there is none to document yet.
> We can see if any dominant form emerges.
>
>> * ``VAR``: Output variable into which the result will be placed.
>> * ``SEP``: String used to join adjacent tokens.
>> * ``<ARGN>``: Tokens to be joined.
>
> I suggest using a definition list instead.

Like this?

:``GENERATE_FLAGS``:
   (List) Additional options to pass to Shiboken.

That's what I ended up using... maybe should have followed up to mention 
that :-). Thanks.

>> Related; is there a way to turn a CMake module file (that is outside of
>> CMake's module directory) into (e.g. HTML) documentation?
>
> No, and I don't want there to be a way to do this with "cmake".
> It will limit our ability to refactor the internal document
> generation in the future.

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)?

Maybe it would help if I rephrase the question:

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?

I expect this is going to be not an unusual problem...

-- 
Matthew