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

[Brad King]

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.

> 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.  It would
be maintained and distributed separately from the rest of CMake and
make its own compatibility guarantees (perhaps even coming with Sphinx).
CMake's copy could be a downstream client just like any other project
that wants to document CMake domain objects.  With this approach
projects could provide documented modules even if they do not build
with CMake (e.g. Qt5).

> 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.

-Brad