[cmake-developers] Converting CMake documentation to reStructuredText and Sphinx

[Stephen Kelly]

Brad King wrote:

> I've prototyped a topic branch to convert CMake's documentation over
> to .rst source files and build them using Sphinx.  It is published
> in my Github repository:
> 
>  https://github.com/bradking/CMake/tree/doc-reStructuredText

Looks interesting.

It looks like property documentation is split now. Will there be new

 cmake --help-prop-tgt COMPILE_DEFINITIONS
 cmake --help-prop-sf COMPILE_DEFINITIONS

commands? Or will there be separate man pages for each type of property?

The commit which factors out the generator expression help references the 
page :manual:`cmake-generator-expressions(5)`, but actually it is in section 
7.

One of the commits also recommends trying man -l cmake-commands.1, but that 
should also be section 7.

In Utilities/Sphinx/CMakeLists.txt, the build-dir/html directory is 
installed unconditionally. That should be wrapped in a check for the option. 

Also in that file, the man page cmake-generator-expressions.7 is not 
installed.

Where will the documentation for individual concepts like 'cmake-languages', 
'cmake-policies', 'cmake-imported-targets', 'cmake-config-packages' etc fit 
into this? As individual pages sibling to cmake-generator-expressions?

> ---------------------------------------------------------------------
> 
> Since this topic makes sweeping changes throughout the source code
> we'll have to schedule a "flag day" on which I will freeze the
> repository and apply the permanent conversion.  Currently I plan
> for this to be just after 2.8.13 is released.

That means we can't add any documentation for concepts until after 2.8.13, 
right? That's unfortunate. I won't have anywhere to point people to when 
they ask me how the KDE buildsystem works.

Thanks,

Steve.