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

[Eric Noulard]

2013/10/14 Brad King <brad.king at kitware.com>:
> On 10/13/2013 4:36 PM, Eric Noulard wrote:
>> I have preliminary question though, since those change makes it possible
>> to write documentation without touching the code are you planning to
>> add missing --help-xxxx to ctest ?
>>
>> Did you plan something along that line?
>
> Yes, but the main issue is that the documentation for CTest variables
> does not exist anywhere in the source right now.  After the transition
> to the new doc system it will be straightforward to add those docs.

Ok that was my question.

> Actually in the new system the --help-* options will just process
> the .rst files in various combinations for display.  For example,
> "cmake --help-commands" just prints "manual/cmake-commands.7.rst"
> which has a section for CTest commands.  Then we need only to expose
> the same set of --help-* options through the ctest command.

Ok I see.
I think the idea of parsing a (sub)set of files may need to be improved.

I'd like the idea to put the documentation as close as possible to
where is it implemented/defined
in order to minimize the discrepancy between the documentation and the
actual implementation.

For "builtin" whose implementation is in C++ code I find it fine to
put a "corresponding .rst file"
in <CMAKE_ROOT>/Help however for Module or even command whose definition is done
in .cmake script file (like most of the CPack documentation) then I'd
rather keep the feature
inside those files.

AFAIU you did just that using include feature
Help/module/FindPNG.rst:
.. cmake-module:: ../../Modules/FindPNG.cmake
.. cmake-module:: ../../Modules/CPack.cmake

However, from my understanding of the "cmRST::ProcessModule"
assumes that all markup are in a "header" I think it would be more convenient
to allow "#.rst:" anywhere in a module and read the file up until then and
   - consume & ignore any line not beginning with '#'
   - interpret extra markup in order to decide whether if the
    documentation is:
       - a command
       - a variable
       - a property etc....
Previous cpack documentation markup would parse any CPack*.cmake file
in the CMAKE_MODULE_PATH
and read those file until the end in order to populate --help-command
and --help-variable

Again, AFAIU you assume that "command" should be documented in
Help/command subdirectory, "property" in Help/property subdir.

i.e. documentation category is built from Help/<dirname>
I don't think this is flexible enough and I'd rather use markup content
in order to do the classification.

Moreover how do you decide which "*.rst" files are parsed for specific
c<command>?
Which one are parsed to build  the doc for:
     cmake
     cpack
     ctest

e.g. currently all CMAKE_xx variable are in Help/variable/
but we can find CPACK_xx variable in there as well i.e:
Help/variable/CPACK_SET_DESTDIR.rst

So for building

cpack --help-variable-list
or
cmake --help-variable-list

how do filter out / include appropriate *.rst files?
In the current state of the source:

cmake --help-variable CPACK_SET_DESTDIR works
whereas
cpack --help-variable CPACK_SET_DESTDIR does not.

Do you want to settle so naming convention for the RST file like a
common prefix?

I guess this aspect may simply be unfinished but my opinion would be
to use "content based classification"
i.e. markup should indicate if we are documenting a variable, a
module, a command etc...
and add some doc *.rst file naming convention which makes it simple to
"classify" documentation
belonging to cmake/cpack/ctest.

What do you think?
-- 
Erk
L'élection n'est pas la démocratie -- http://www.le-message.org