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.

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.
+To add a module to the CMake documentation, follow these steps:
-There are three types of comments that can be in the block:
 
-1. The brief description of the module, this is done by:
+1. Add file ``Help/module/FindXxx.rst`` containing just the line::
-# - a small description
 
-2. A paragraph of text.  This is done with all text that has a single
+    .. cmake-module:: ../../Modules/FindXxx.cmake
-space between the # and the text.  To create a new paragraph, just
-put a # with no text on the line.
 
-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
+   Keep the toctree in sorted order!
-# 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?
-#
 
-Test the documentation formatting by running "cmake --help-module FindXxx".
+3. Add to the top of ``Modules/FindXxx.cmake`` a #-comment of the form::
-Edit the comments until the output of this command looks satisfactory.
 
-To have a .cmake file in this directory NOT show up in the
+    #.rst:
-modules documentation, you should start the file with a blank
+    # FindXxx
-line.
+    # -------
+    #
+    # ...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",
+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, 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: