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

[Matthew Woehlke]

On 2014-01-08 15:35, Brad King wrote:
> On 01/08/2014 01:52 PM, Matthew Woehlke wrote:
>> On 2013-12-19 11:21, Brad King wrote:
>>> Sphinx does not support magic cross-referencing to external documents.
>>
>> If that's really true, that's a pretty big drawback of docutils vs. e.g.
>> doxygen, which has very good support for external references.
>
> I can't say for sure it is not possible.  Perhaps there is a way to
> export Sphinx Domain objects for reference by external documents
> whose build configuration references a specific publication URL of
> the upstream objects, but I'm not familiar with it.

Neither am I :-), but I would be surprised if there isn't some 
implementation somewhere. I will try to look into this some time and 
will get back to you if I find anything.

>> This places a significant maintenance burden on projects and leads to
>> their being umpteen copies of the CMake reST additions.
>
> Ideally someone would create a dedicated CMake reST documentation
> project like the CMakeDocUtils package in your example.

I debated whether or not to suggest that in the previous mail due to not 
knowing how it would work out with the CMake project itself. But...

> CMake's copy could be a downstream client just like any other project
> that wants to document CMake domain objects.

...since it seems that CMake would be amenable to using this, then I 
agree, this is probably the best solution.

I think we are on the same page now; thanks for a productive discussion!

> With this approach projects could provide documented modules even if
> they do not build with CMake (e.g. Qt5).

That's a good point :-).

>> Do you really anticipate that the syntax for declaring documentation is
>> going to change?
>
> Yes.  The new documentation system is very young and will likely
> change as it matures.

To be clear, I meant *only* the '#.rst' syntax (i.e. the code to extract 
the reST markup from a CMake module). I would not expect *that* to 
change again?

Stuff within the reST domain, sure, I can see that changing.

-- 
Matthew