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

[Brad King]

On 10/15/2013 05:57 AM, Eric Noulard wrote:
> 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

It is allowed anywhere in the module already.  Any "#.rst:" line
enables scanning of the immediately following comment block.

>    - interpret extra markup in order to decide whether if the
>     documentation is:
>        - a command
>        - a variable
>        - a property etc....

That's what the cmake domain directives do.  They can appear anywhere
in the documents.

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

The CMake builtin (C++) commands and properties go there.  Others
can too if we want.

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

That's what the cmake domain directives do.  The Help/<type>
organization just saves the need to use the domain directives for
everything explicitly.  Look at the CPack module example for
defining variables.  They can be cross-referenced and are indexed
in the html help just like the Help/<type> documents.

The only part missing currently is that "--help-variable-list"
and "--help-variable X" do not support directive-defined variables
(and similarly for commands/macros/functions).  This would be pretty
expensive to support because we would have to scan all documents
for variable definitions to produce the list.  The fact that this
works for CPack now is because there are only a small number of
modules to scan.  Some kind of pre-computed index would be needed.
However, see the last paragraph of this message.

> Moreover how do you decide which "*.rst" files are parsed for specific
> c<command>?
[snip]
> how do filter out / include appropriate *.rst files?

We don't.  The cmake-commands.7 and cmake-variables.7 manuals are
organized into sections accordingly.  The toctree directives determine
the organization.  Each section leads with an explanation of when its
content can be used (if only in the section name).  In cases that the
constraints are more granular the information should be in the item's
individual documentation, or the manuals should be organized further.

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

No, we just need to teach ctest and cpack the same help options that
cmake knows.  There is no reason to exclude CPack variables from CMake
help or vice versa.  Any of the commands should be able to print any
of the documentation.  The cpack variables are meant for use in CMake
code which are processed by the cmake tool anyway.

The current state of the topic does the minimum necessary to reproduce
existing help options as much as possible in the new system.  Once we
transition then new functionality can be added.  However, I'd like to
change the focus from cmake/ctest/cpack command-oriented organization to
a manual-oriented organization.  That will allow many more topics to
be covered (like cmake-generator-expressions.7).  Over time we can find
new workflows for jumping to help at the command-line or elsewhere.

-Brad