View Issue Details Jump to Notes ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0015587CMake(No Category)public2015-05-26 17:262016-06-10 14:31
ReporterStephen Kelly 
Assigned ToKitware Robot 
PrioritynormalSeverityminorReproducibilityhave not tried
StatusclosedResolutionmoved 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0015587: Add more RST markup to documentation
DescriptionThere are lots of places in the CMake documentation which have suboptimal reStructuredText formatting. Fixing up some of that would be great. There is information about writing help files here:

 http://www.cmake.org/cmake/help/v3.0/manual/cmake-developer.7.html#help [^]

For example on this page, the CMAKE_PARENT_LIST_FILE could be a link, but is currently not:

 http://www.cmake.org/cmake/help/v3.0/variable/CMAKE_CURRENT_LIST_FILE.html [^]

There are many other examples and it would make a huge improvement to the documentation to systematically improve documentation pages like that.
TagsNo tags attached.
Attached Filespatch file icon help_command.patch [^] (76,148 bytes) 2015-06-03 18:10 [Show Content]

 Relationships

  Notes
(0038805)
Brad King (manager)
2015-05-27 08:29

Yes. When we first converted to reStructuredText it was done via an automated conversion from the older internal format. We've been incrementally converting documents prior to making other modifications to them.
(0038817)
Michael Scott (reporter)
2015-05-28 17:14

I've started having a look at the developer information on documentation. Is there a particular part of the documentation that could do with improving or is it the files all round that could with the kind of improvements given above?
(0038819)
Brad King (manager)
2015-05-29 09:41

Re 0015587:0038817: Thanks! Any documentation files that have not been modernized with inline markup for cross-referencing are candidates.

Please see the "Help" section of the cmake-developer(7) manual:

 http://www.cmake.org/cmake/help/v3.2/manual/cmake-developer.7.html#help [^]

for an explanation of how the cross-referencing works and the preferred reStructuredText style.

For example, the add_custom_target() command has full markup and uses a definition list for the command options:

 http://www.cmake.org/cmake/help/v3.2/command/add_custom_target.html [^]

An example of a command that has not been updated is list():

 http://www.cmake.org/cmake/help/v3.2/command/list.html [^]
(0038881)
Michael Scott (reporter)
2015-06-03 18:19

Hi Brad,

I've just uploaded a patch file containing changes to the Help/command rst files, to add in some more rst markup. Do they look okay?

There are a couple of things to mention with the proposed changes:
- create_test_sourcelist generates sphinx warnings because I added some variable cross references, but these apparently don't exist, I left them in as I figured it's probably better to know they're incorrect than not
- I tried to cross reference all the properties in get_cmake_property, but some of them don't seem to exist, so I left them as they were
- I was a bit unsure about the correct usage of " and `` at times, as there were cases of both being used, so there might be a few cases where I've used `` incorrectly, but generally when I was unsure about this I left it as is

Cheers,
Michael
(0038883)
Brad King (manager)
2015-06-04 08:56

Re 0015587:0038881: Thanks! Please commit locally and use "git format-patch" to produce the patch file. Then send it to the developer mailing list for review as mentioned in CONTRIBUTING.rst. Most review should take place there.

In response to your bullets:

* We don't want any sphinx warnings to be left. The missing variables should either be added or just referenced by ``inline-literal`` syntax instead. When in doubt, check the source code to see if a variable is really defined or not.

* For the create_test_sourcelist variables you can define them locally with ".. variable:" directives right in that documentation. References to them within the same document can just be done with ``varname`` though as mentioned in the style guide I linked.

* The tiny subset of properties listed in get_cmake_property is left from before we had a dedicated cmake-properties manual. Instead of listing them here you could just say "see the :manual:`cmake-properties(7)` manual for available properties". You could dig into the source code to see if the non-documented properties actually exist. If so, please add documents for them.

* The ``inline-literal`` syntax should be used when referring to a defined technical/code construct. The "double-quotes" syntax can be used as it might be in prose normally. Many instances of "double-quotes" are likely left from before we used rst markup and may need to be converted to ``inline-literal`` syntax.
(0038885)
Michael Scott (reporter)
2015-06-04 18:05

Just so I don't submit the patch in the wrong way, do I simply email the contents of the patch file format-patch produces to the developer mailing list, or should it be an attachment with some general information on the batch in the message body? Does the email subject need to be in a specific format, e.g. contain the issue ID, or is it fine to just use the subject format-patch produces?

Sorry for all the questions, I haven't used git/patches particularly before now.
(0038894)
Brad King (manager)
2015-06-08 10:36

Re 0015587:0038885: The simplest approach is to take the file produced by "git format-patch" and send it as an attachment. We have no requirements on the subject line or body of the outer message.

More advanced users can use "git send-email" to send the patch inline but that takes some experience to understand and is not necessary.
(0042783)
Kitware Robot (administrator)
2016-06-10 14:29

Resolving issue as `moved`.

This issue tracker is no longer used. Further discussion of this issue may take place in the current CMake Issues page linked in the banner at the top of this page.

 Issue History
Date Modified Username Field Change
2015-05-26 17:26 Stephen Kelly New Issue
2015-05-27 08:29 Brad King Note Added: 0038805
2015-05-28 17:14 Michael Scott Note Added: 0038817
2015-05-29 09:41 Brad King Note Added: 0038819
2015-06-03 18:10 Michael Scott File Added: help_command.patch
2015-06-03 18:19 Michael Scott Note Added: 0038881
2015-06-04 08:56 Brad King Note Added: 0038883
2015-06-04 18:05 Michael Scott Note Added: 0038885
2015-06-08 10:36 Brad King Note Added: 0038894
2015-06-11 02:29 rtryutugd Note Added: 0038907
2015-06-11 08:22 Brad King Note Deleted: 0038907
2016-06-10 14:29 Kitware Robot Note Added: 0042783
2016-06-10 14:29 Kitware Robot Status new => resolved
2016-06-10 14:29 Kitware Robot Resolution open => moved
2016-06-10 14:29 Kitware Robot Assigned To => Kitware Robot
2016-06-10 14:31 Kitware Robot Status resolved => closed


Copyright © 2000 - 2018 MantisBT Team