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.
This commit is contained in:
Brad King 2013-10-15 14:47:12 -04:00
parent a77e308693
commit 7038a93a7e
1 changed files with 41 additions and 23 deletions

View File

@ -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. 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. 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 After the documentation, leave a *BLANK* line, and then add a
copyright and licence notice block like this one: copyright and licence notice block like this one: