[Cmake-commits] CMake branch, next, updated. v2.8.12-4022-gb7fa7f7

[Brad King]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".

The branch, next has been updated
       via  b7fa7f7f82931173aa9c66962b00deed44b5bad8 (commit)
       via  92b4e3fb5d48af6855e7796a789b369c3d27b382 (commit)
      from  b54fcb80fb0cee80026e446622242305e8ea6e5e (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b7fa7f7f82931173aa9c66962b00deed44b5bad8
commit b7fa7f7f82931173aa9c66962b00deed44b5bad8
Merge: b54fcb8 92b4e3f
Author:     Brad King <brad.king at kitware.com>
AuthorDate: Tue Oct 15 15:29:15 2013 -0400
Commit:     CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Tue Oct 15 15:29:15 2013 -0400

    Merge topic 'doc-reStructuredText' into next
    
    92b4e3f Modules/readme.txt: Update steps to add module documentation


http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=92b4e3fb5d48af6855e7796a789b369c3d27b382
commit 92b4e3fb5d48af6855e7796a789b369c3d27b382
Author:     Brad King <brad.king at kitware.com>
AuthorDate: Tue Oct 15 14:47:12 2013 -0400
Commit:     Brad King <brad.king at kitware.com>
CommitDate: Tue Oct 15 14:47:12 2013 -0400

    Modules/readme.txt: Update steps to add module documentation
    
    Replace the old module documentation instructions with steps to add
    reStructuredText documentation that will be built by Sphinx.

diff --git a/Modules/readme.txt b/Modules/readme.txt
index 2f11994..2593b4f 100644
--- a/Modules/readme.txt
+++ b/Modules/readme.txt
@@ -58,36 +58,54 @@ descriptions of any the users can use to control stuff.
 You really should also provide backwards compatibility any old settings that were actually in use.
 Make sure you comment them as deprecated, so that no-one starts using them.
 
-To correctly document a module, create a comment block at the top with # comments.
-There are three types of comments that can be in the block:
+To add a module to the CMake documentation, follow these steps:
 
-1. The brief description of the module, this is done by:
-# - a small description
+1. Add file ``Help/module/FindXxx.rst`` containing just the line::
 
-2. A paragraph of text.  This is done with all text that has a single
-space between the # and the text.  To create a new paragraph, just
-put a # with no text on the line.
+    .. cmake-module:: ../../Modules/FindXxx.cmake
 
-3. A verbatim line.  This is done with two spaces between the # and the text.
+2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
+   toctree directive as::
 
-For example:
+    /module/FindXxx
 
-# - This is a cool module
-# This module does really cool stuff.
-# It can do even more than you think.
-#
-# It even needs to paragraphs to tell you about it.
-# And it defines the following variables:
-#  VAR_COOL - this is great isn't it?
-#  VAR_REALLY_COOL - cool right?
-#
+   Keep the toctree in sorted order!
+
+3. Add to the top of ``Modules/FindXxx.cmake`` a #-comment of the form::
+
+    #.rst:
+    # FindXxx
+    # -------
+    #
+    # ...reStructuredText documentation of module...
+
+   Comment blocks starting with the line ``#.rst:`` may appear anywhere
+   in the file.
+
+For example::
+
+ #.rst
+ # FindXxx
+ # -------
+ #
+ # This is a cool module.
+ # This module does really cool stuff.
+ # It can do even more than you think.
+ #
+ # It even needs two paragraphs to tell you about it.
+ # And it defines the following variables:
+ #
+ # * VAR_COOL: this is great isn't it?
+ # * VAR_REALLY_COOL: cool right?
 
-Test the documentation formatting by running "cmake --help-module FindXxx".
-Edit the comments until the output of this command looks satisfactory.
+Test the documentation formatting by running "cmake --help-module FindXxx",
+and ideally by enabling the SPHINX_HTML and SPHINX_MAN options to build the
+documentation.  Edit the comments until generated documentation looks
+satisfactory.
 
-To have a .cmake file in this directory NOT show up in the
-modules documentation, you should start the file with a blank
-line.
+To have a .cmake file in this directory NOT show up in the modules
+documentation, simply leave out the ``Help/module/<module>.rst`` file and the
+``Help/manual/cmake-modules.7.rst`` toctree entry.
 
 After the documentation, leave a *BLANK* line, and then add a
 copyright and licence notice block like this one:

-----------------------------------------------------------------------

Summary of changes:
 Modules/readme.txt |   64 +++++++++++++++++++++++++++++++++------------------
 1 files changed, 41 insertions(+), 23 deletions(-)


hooks/post-receive
-- 
CMake