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

[Robert Maynard]

Stephen,

As far as 'concepts' documentation is concerned, why don't we work together
to write a CMake blog article that rolls together the documentation
and an example?
Would that give the KDE people a good enough source for how to use the feature?

On Thu, Oct 10, 2013 at 12:02 PM, Stephen Kelly <steveire at gmail.com> wrote:
> 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.
>
>
> --
>
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
>
> Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ
>
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers