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

[Eric Noulard]

2013/10/15 Brad King <brad.king at kitware.com>:
> 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.

Ok right I miss-read the code.

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

Ok right again. I see:
.. cmake:variable::
.. cmake:command::

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

Yes right the dynamicity of the approach has a cost but you can do that
only when --help-xxx is invoked or build a new 'cdoc'
command that would include pre-parsed version of every *.rst file
in the CMake source tree.

If you read documentation you'll be opening probably a bunch of files
anyway so doing it with man, a web browser or cxxxx command does
not change much.

What should be avoided is to do this parsing when no doc at all is requested,
I had the remark when I contributed the cpack doc (may be from you if
I remember it well).


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

I disagree I think there is because:

  1) cpack may be used without CMake

  2) Many CMAKE_xxx variable have strictly no impact on cpack.
      CMAKE_BUILD_TYPE, CMAKE_SKIP_INSTALL_ALL_DEPENDENCY,
CMAKE_INSTALL_PREFIX, ..

  4) In the same way why would add_executable or add_test or
add_library appear in
     cpack --help-command-list

  3) Shell completion is very handy to get fast help, since they rely
      on --help-XXXX-list it is faster to use if the list is as short
as necessary.

> 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 fact that CPack uses cmake scripts does not mean the cmake **command**
is processing the CPack scripts.

I'm sure you know that but cpack -G NSIS does not call cmake command,
it is simply creating a cmake script processing object instance.

In fact CPack is only using the the "cmake processing mode" commands so that
at least
cpack --help-command-list should exclude non-scripting mode CMake commands.

b.t.w. this is the case currently. Leaving that out would be a regression.

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

ok just wanted to point out that builtin doc for variable, command,
property is quite good
and personnally I'd rather

$ cmake --help-command-list | grep add
or
$ cmake --help-variable-list | grep FLAGS
or
$ cpack --help-variable-list | grep NSIS | less

rather than browsing manual oriented doc.
When I'm looking for topic/concept oriented doc like "generator-expressions"
this is another story for which I would advocate the addition of
--help-concept as proposed by Stephen.

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

You are the boss prioritizing the goal, I was just pointing out the fact
that having list and detail of variable, command, property
**on the command line** is very helpful to me.

My personal opinion though.


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