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

[Brad King]

On 10/10/2013 12:02 PM, Stephen Kelly wrote:
> 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?

It was always split and "--help-property FOO" would pick one (or all?)
before.  Now it picks all matching property documents.

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

Fixed in my local repo, thanks.

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

That's the demonstration commit which won't be in the final conversion.

> In Utilities/Sphinx/CMakeLists.txt, the build-dir/html directory is 
> installed unconditionally. That should be wrapped in a check for the option. 
[snip]
> Also in that file, the man page cmake-generator-expressions.7 is not 
> installed.

Both already fixed since I pushed the demonstration topic, thanks.

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

Yes, exactly.  Note cmake-policies.7 is already a manual.  Even though
it is the reference of defined policies now we can add more sections to
it to have concept introduction and examples.

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

There are plenty of Wiki sites that can stage the documentation until
the new system is ready.  I don't want to add --help-concepts just to
drop it again one release later or have to support it forever when the
new system has no explicit notion of a concept.

The topic breaks some of the existing --help-* commands like --help-full,
--help-man, --help-html and a few others, plus changes the output format
of the ones that still work.  This is best done with a major version bump.

-Brad