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

[Matthew Woehlke]

On 2013-12-19 11:21, Brad King wrote:
> 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://...).

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. 
Considering that docutils is supposed to be the de-facto standard for 
documenting Python, which has all sorts of external modules, I'd be 
surprised if there isn't a solution to this problem already existing.

Even if not, from what I know of reST, it wouldn't be all that difficult 
to create one. (At worst, you'd need to introduce a new interpreted text 
role for external links, but that's not exactly the end of the world. 
And if you reuse doxygen's tagfile format, suddenly you can link to 
doxygen-generated C++ doxygen from reST :-). Again, assuming that hasn't 
already been done...)

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

Sure. I just feel like this should be solvable like:

find_package(CMakeDocUtils)
include(${CMakeDocUtilsUseFile})
cmake_generate_documentation(...)

...where ideally CMakeDocUtils is provided by CMake itself (albeit free 
to rely on being able to find other external tools, e.g. Python).

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

This places a significant maintenance burden on projects and leads to 
their being umpteen copies of the CMake reST additions. For small 
projects, this could even end up being more "code" that the project 
itself! I fail to see how this is in any way other than a Bad Thing.

> Another approach is to use sed+rst2html to extract
> and process .rst markup from inside .cmake file comments.

Do you really anticipate that the syntax for declaring documentation is 
going to change? I would think that, at the very least, something to 
extract the reST text from a CMake module should be provided by CMake. 
(Again, I'll assert that such utility does NOT need to be self-contained 
and is free to depend on e.g. Python being available.)



 From the perspective as a user wanting to do this, the question is if I 
spend a *lot* of effort reinventing the wheel in my own project, which 
may initially get the job done but incurs an ongoing maintenance burden 
(and/or rapidly bitrots), or do I spend that effort taking CMake's 
existing documentation support and making it available to external 
users, so that it benefits *everyone* and distributes the maintenance 
burden?

Hopefully that helps to understand my perspective.

Thanks,

-- 
Matthew