Help/dev/documentation.rst - third_party/cmake - Git at Google

 CMake Documentation Guide
 *************************

 The following is a guide to the CMake documentation source for developers.
 See documentation on `CMake Development`_ for more information.

 .. _`CMake Development`: README.rst

 Help
 ====

 The ``Help`` directory contains CMake help manual source files.
 They are written using the `reStructuredText`_ markup syntax and
 processed by `Sphinx`_ to generate the CMake help manuals.

 .. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
 .. _`Sphinx`: http://sphinx-doc.org

 Markup Constructs
 -----------------

 In addition to using Sphinx to generate the CMake help manuals, we
 also use a C++-implemented document processor to print documents for
 the ``--help-*`` command-line help options.  It supports a subset of
 reStructuredText markup.  When authoring or modifying documents,
 please verify that the command-line help looks good in addition to the
 Sphinx-generated html and man pages.

 The command-line help processor supports the following constructs
 defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.

 ..
  Note: This list must be kept consistent with the cmRST implementation.

 CMake Domain directives
  Directives defined in the `CMake Domain`_ for defining CMake
  documentation objects are printed in command-line help output as
  if the lines were normal paragraph text with interpretation.

 CMake Domain interpreted text roles
  Interpreted text roles defined in the `CMake Domain`_ for
  cross-referencing CMake documentation objects are replaced by their
  link text in command-line help output.  Other roles are printed
  literally and not processed.

 ``code-block`` directive
  Add a literal code block without interpretation.  The command-line
  help processor prints the block content without the leading directive
  line and with common indentation replaced by one space.

 ``include`` directive
  Include another document source file.  The command-line help
  processor prints the included document inline with the referencing
  document.

 literal block after ``::``
  A paragraph ending in ``::`` followed by a blank line treats
  the following indented block as literal text without interpretation.
  The command-line help processor prints the ``::`` literally and
  prints the block content with common indentation replaced by one
  space.

 ``note`` directive
  Call out a side note.  The command-line help processor prints the
  block content as if the lines were normal paragraph text with
  interpretation.

 ``parsed-literal`` directive
  Add a literal block with markup interpretation.  The command-line
  help processor prints the block content without the leading
  directive line and with common indentation replaced by one space.

 ``productionlist`` directive
  Render context-free grammar productions.  The command-line help
  processor prints the block content as if the lines were normal
  paragraph text with interpretation.

 ``replace`` directive
  Define a ``|substitution|`` replacement.
  The command-line help processor requires a substitution replacement
  to be defined before it is referenced.

 ``|substitution|`` reference
  Reference a substitution replacement previously defined by
  the ``replace`` directive.  The command-line help processor
  performs the substitution and replaces all newlines in the
  replacement text with spaces.

 ``toctree`` directive
  Include other document sources in the Table-of-Contents
  document tree.  The command-line help processor prints
  the referenced documents inline as part of the referencing
  document.

 Inline markup constructs not listed above are printed literally in the
 command-line help output.  We prefer to use inline markup constructs that
 look correct in source form, so avoid use of \\-escapes in favor of inline
 literals when possible.

 Explicit markup blocks not matching directives listed above are removed from
 command-line help output.  Do not use them, except for plain ``..`` comments
 that are removed by Sphinx too.

 Note that nested indentation of blocks is not recognized by the
 command-line help processor.  Therefore:

 * Explicit markup blocks are recognized only when not indented
   inside other blocks.

 * Literal blocks after paragraphs ending in ``::`` but not
   at the top indentation level may consume all indented lines
   following them.

 Try to avoid these cases in practice.

 CMake Domain
 ------------

 CMake adds a `Sphinx Domain`_ called ``cmake``, also called the
 "CMake Domain".  It defines several "object" types for CMake
 documentation:

 ``command``
  A CMake language command.

 ``generator``
  A CMake native build system generator.
  See the `cmake(1)`_ command-line tool's ``-G`` option.

 ``manual``
  A CMake manual page, like the `cmake(1)`_ manual.

 ``module``
  A CMake module.
  See the `cmake-modules(7)`_ manual
  and the `include()`_ command.

 ``policy``
  A CMake policy.
  See the `cmake-policies(7)`_ manual
  and the `cmake_policy()`_ command.

 ``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt``
  A CMake cache, directory, global, source file, installed file, test,
  or target property, respectively.  See the `cmake-properties(7)`_
  manual and the `set_property()`_ command.

 ``variable``
  A CMake language variable.
  See the `cmake-variables(7)`_ manual
  and the `set()`_ command.

 Documentation objects in the CMake Domain come from two sources.
 First, the CMake extension to Sphinx transforms every document named
 with the form ``Help/<type>/<file-name>.rst`` to a domain object with
 type ``<type>``.  The object name is extracted from the document title,
 which is expected to be of the form::

  <object-name>
  -------------

 and to appear at or near the top of the ``.rst`` file before any other
 lines starting in a letter, digit, or ``<``.  If no such title appears
 literally in the ``.rst`` file, the object name is the ``<file-name>``.
 If a title does appear, it is expected that ``<file-name>`` is equal
 to ``<object-name>`` with any ``<`` and ``>`` characters removed.

 Second, the CMake Domain provides directives to define objects inside
 other documents:

 .. code-block:: rst

  .. command:: <command-name>

   This indented block documents <command-name>.

  .. variable:: <variable-name>

   This indented block documents <variable-name>.

 Object types for which no directive is available must be defined using
 the first approach above.

 .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
 .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
 .. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html
 .. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html
 .. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html
 .. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html
 .. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html
 .. _`include()`: https://cmake.org/cmake/help/latest/command/include.html
 .. _`set()`: https://cmake.org/cmake/help/latest/command/set.html
 .. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html

 Cross-References
 ----------------

 Sphinx uses reStructuredText interpreted text roles to provide
 cross-reference syntax.  The `CMake Domain`_ provides for each
 domain object type a role of the same name to cross-reference it.
 CMake Domain roles are inline markup of the forms::

  :type:`name`
  :type:`text <name>`

 where ``type`` is the domain object type and ``name`` is the
 domain object name.  In the first form the link text will be
 ``name`` (or ``name()`` if the type is ``command``) and in
 the second form the link text will be the explicit ``text``.
 For example, the code:

 .. code-block:: rst

  * The :command:`list` command.
  * The :command:`list(APPEND)` sub-command.
  * The :command:`list() command <list>`.
  * The :command:`list(APPEND) sub-command <list>`.
  * The :variable:`CMAKE_VERSION` variable.
  * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.

 produces:

 * The `list()`_ command.
 * The `list(APPEND)`_ sub-command.
 * The `list() command`_.
 * The `list(APPEND) sub-command`_.
 * The `CMAKE_VERSION`_ variable.
 * The `OUTPUT_NAME_<CONFIG>`_ target property.

 Note that CMake Domain roles differ from Sphinx and reStructuredText
 convention in that the form ``a<b>``, without a space preceding ``<``,
 is interpreted as a name instead of link text with an explicit target.
 This is necessary because we use ``<placeholders>`` frequently in
 object names like ``OUTPUT_NAME_<CONFIG>``.  The form ``a <b>``,
 with a space preceding ``<``, is still interpreted as a link text
 with an explicit target.

 .. _`list()`: https://cmake.org/cmake/help/latest/command/list.html
 .. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html
 .. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html
 .. _`list() command`: https://cmake.org/cmake/help/latest/command/list.html
 .. _`CMAKE_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_VERSION.html
 .. _`OUTPUT_NAME_<CONFIG>`: https://cmake.org/cmake/help/latest/prop_tgt/OUTPUT_NAME_CONFIG.html

 Style
 -----

 Style: Section Headers
 ^^^^^^^^^^^^^^^^^^^^^^

 When marking section titles, make the section decoration line as long as
 the title text.  Use only a line below the title, not above. For
 example:

 .. code-block:: rst

   Title Text
   ----------

 Capitalize the first letter of each non-minor word in the title.

 The section header underline character hierarchy is

 * ``#``: Manual group (part) in the master document
 * ``*``: Manual (chapter) title
 * ``=``: Section within a manual
 * ``-``: Subsection or `CMake Domain`_ object document title
 * ``^``: Subsubsection or `CMake Domain`_ object document section
 * ``"``: Paragraph or `CMake Domain`_ object document subsection

 Style: Whitespace
 ^^^^^^^^^^^^^^^^^

 Use two spaces for indentation.  Use two spaces between sentences in
 prose.

 Style: Line Length
 ^^^^^^^^^^^^^^^^^^

 Prefer to restrict the width of lines to 75-80 columns.  This is not a
 hard restriction, but writing new paragraphs wrapped at 75 columns
 allows space for adding minor content without significant re-wrapping of
 content.

 Style: Prose
 ^^^^^^^^^^^^

 Use American English spellings in prose.

 Style: Starting Literal Blocks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Prefer to mark the start of literal blocks with ``::`` at the end of
 the preceding paragraph. In cases where the following block gets
 a ``code-block`` marker, put a single ``:`` at the end of the preceding
 paragraph.

 Style: CMake Command Signatures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Command signatures should be marked up as plain literal blocks, not as
 cmake ``code-blocks``.

 Signatures are separated from preceding content by a section header.
 That is, use:

 .. code-block:: rst

   ... preceding paragraph.

   Normal Libraries
   ^^^^^^^^^^^^^^^^

   ::

     add_library(<lib> ...)

   This signature is used for ...

 Signatures of commands should wrap optional parts with square brackets,
 and should mark list of optional arguments with an ellipsis (``...``).
 Elements of the signature which are specified by the user should be
 specified with angle brackets, and may be referred to in prose using
 ``inline-literal`` syntax.

 Style: Boolean Constants
 ^^^^^^^^^^^^^^^^^^^^^^^^

 Use "``OFF``" and "``ON``" for boolean values which can be modified by
 the user, such as ``POSITION_INDEPENDENT_CODE``.  Such properties
 may be "enabled" and "disabled". Use "``True``" and "``False``" for
 inherent values which can't be modified after being set, such as the
 ``IMPORTED`` property of a build target.

 Style: Inline Literals
 ^^^^^^^^^^^^^^^^^^^^^^

 Mark up references to keywords in signatures, file names, and other
 technical terms with ``inline-literal`` syntax, for example:

 .. code-block:: rst

   If ``WIN32`` is used with :command:`add_executable`, the
   :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
   creates the file ``<name>.exe`` on Windows.

 Style: Cross-References
 ^^^^^^^^^^^^^^^^^^^^^^^

 Mark up linkable references as links, including repeats.
 An alternative, which is used by wikipedia
 (`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
 is to link to a reference only once per article. That style is not used
 in CMake documentation.

 Style: Referencing CMake Concepts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 If referring to a concept which corresponds to a property, and that
 concept is described in a high-level manual, prefer to link to the
 manual section instead of the property. For example:

 .. code-block:: rst

   This command creates an :ref:`Imported Target <Imported Targets>`.

 instead of:

 .. code-block:: rst

   This command creates an :prop_tgt:`IMPORTED` target.

 The latter should be used only when referring specifically to the
 property.

 References to manual sections are not automatically created by creating
 a section, but code such as:

 .. code-block:: rst

   .. _`Imported Targets`:

 creates a suitable anchor.  Use an anchor name which matches the name
 of the corresponding section.  Refer to the anchor using a
 cross-reference with specified text.

 Imported Targets need the ``IMPORTED`` term marked up with care in
 particular because the term may refer to a command keyword, a target
 property, or a concept.

 Where a property, command or variable is related conceptually to others,
 by for example, being related to the buildsystem description, generator
 expressions or Qt, each relevant property, command or variable should
 link to the primary manual, which provides high-level information.  Only
 particular information relating to the command should be in the
 documentation of the command.

 Style: Referencing CMake Domain Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 When referring to `CMake Domain`_ objects such as properties, variables,
 commands etc, prefer to link to the target object and follow that with
 the type of object it is.  For example:

 .. code-block:: rst

   Set the :prop_tgt:`AUTOMOC` target property to ``ON``.

 Instead of

 .. code-block:: rst

   Set the target property :prop_tgt:`AUTOMOC` to ``ON``.

 The ``policy`` directive is an exception, and the type us usually
 referred to before the link:

 .. code-block:: rst

   If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ...

 However, markup self-references with ``inline-literal`` syntax.
 For example, within the ``add_executable`` command documentation, use

 .. code-block:: rst

   ``add_executable``

 not

 .. code-block:: rst

   :command:`add_executable`

 which is used elsewhere.

 Modules
 =======

 The ``Modules`` directory contains CMake-language ``.cmake`` module files.

 Module Documentation
 --------------------

 To document CMake module ``Modules/<module-name>.cmake``, modify
 ``Help/manual/cmake-modules.7.rst`` to reference the module in the
 ``toctree`` directive, in sorted order, as::

  /module/<module-name>

 Then add the module document file ``Help/module/<module-name>.rst``
 containing just the line::

  .. cmake-module:: ../../Modules/<module-name>.cmake

 The ``cmake-module`` directive will scan the module file to extract
 reStructuredText markup from comment blocks that start in ``.rst:``.
 At the top of ``Modules/<module-name>.cmake``, begin with the following
 license notice:

 ::

  # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
  # file Copyright.txt or https://cmake.org/licensing for details.

 After this notice, add a *BLANK* line.  Then, add documentation using
 a `Bracket Comment`_ of the form:

 ::

   #[=======================================================================[.rst:
   <module-name>
   -------------

   <reStructuredText documentation of module>
   #]=======================================================================]

 Any number of ``=`` may be used in the opening and closing brackets
 as long as they match.  Content on the line containing the closing
 bracket is excluded if and only if the line starts in ``#``.

 Additional such ``.rst:`` comments may appear anywhere in the module file.
 All such comments must start with ``#`` in the first column.

 For example, a ``Findxxx.cmake`` module may contain:

 ::

   # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   # file Copyright.txt or https://cmake.org/licensing for details.

   #[=======================================================================[.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?
   #]=======================================================================]

   <code>

   #[=======================================================================[.rst:
   .. command:: xxx_do_something

    This command does something for Xxx::

     xxx_do_something(some arguments)
   #]=======================================================================]
   macro(xxx_do_something)
     <code>
   endmacro()

 Test the documentation formatting by running
 ``cmake --help-module <module-name>``, and also 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-name>.rst``
 file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.

 .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment
	CMake Documentation Guide
	*************************

	The following is a guide to the CMake documentation source for developers.
	See documentation on `CMake Development`_ for more information.

	.. _`CMake Development`: README.rst

	Help
	====

	The ``Help`` directory contains CMake help manual source files.
	They are written using the `reStructuredText`_ markup syntax and
	processed by `Sphinx`_ to generate the CMake help manuals.

	.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
	.. _`Sphinx`: http://sphinx-doc.org

	Markup Constructs
	-----------------

	In addition to using Sphinx to generate the CMake help manuals, we
	also use a C++-implemented document processor to print documents for
	the ``--help-*`` command-line help options. It supports a subset of
	reStructuredText markup. When authoring or modifying documents,
	please verify that the command-line help looks good in addition to the
	Sphinx-generated html and man pages.

	The command-line help processor supports the following constructs
	defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.

	..
	Note: This list must be kept consistent with the cmRST implementation.

	CMake Domain directives
	Directives defined in the `CMake Domain`_ for defining CMake
	documentation objects are printed in command-line help output as
	if the lines were normal paragraph text with interpretation.

	CMake Domain interpreted text roles
	Interpreted text roles defined in the `CMake Domain`_ for
	cross-referencing CMake documentation objects are replaced by their
	link text in command-line help output. Other roles are printed
	literally and not processed.

	``code-block`` directive
	Add a literal code block without interpretation. The command-line
	help processor prints the block content without the leading directive
	line and with common indentation replaced by one space.

	``include`` directive
	Include another document source file. The command-line help
	processor prints the included document inline with the referencing
	document.

	literal block after ``::``
	A paragraph ending in ``::`` followed by a blank line treats
	the following indented block as literal text without interpretation.
	The command-line help processor prints the ``::`` literally and
	prints the block content with common indentation replaced by one
	space.

	``note`` directive
	Call out a side note. The command-line help processor prints the
	block content as if the lines were normal paragraph text with
	interpretation.

	``parsed-literal`` directive
	Add a literal block with markup interpretation. The command-line
	help processor prints the block content without the leading
	directive line and with common indentation replaced by one space.

	``productionlist`` directive
	Render context-free grammar productions. The command-line help
	processor prints the block content as if the lines were normal
	paragraph text with interpretation.

	``replace`` directive
	Define a ``\|substitution\|`` replacement.
	The command-line help processor requires a substitution replacement
	to be defined before it is referenced.

	``\|substitution\|`` reference
	Reference a substitution replacement previously defined by
	the ``replace`` directive. The command-line help processor
	performs the substitution and replaces all newlines in the
	replacement text with spaces.

	``toctree`` directive
	Include other document sources in the Table-of-Contents
	document tree. The command-line help processor prints
	the referenced documents inline as part of the referencing
	document.

	Inline markup constructs not listed above are printed literally in the
	command-line help output. We prefer to use inline markup constructs that
	look correct in source form, so avoid use of \\-escapes in favor of inline
	literals when possible.

	Explicit markup blocks not matching directives listed above are removed from
	command-line help output. Do not use them, except for plain ``..`` comments
	that are removed by Sphinx too.

	Note that nested indentation of blocks is not recognized by the
	command-line help processor. Therefore:

	* Explicit markup blocks are recognized only when not indented
	inside other blocks.

	* Literal blocks after paragraphs ending in ``::`` but not
	at the top indentation level may consume all indented lines
	following them.

	Try to avoid these cases in practice.

	CMake Domain
	------------

	CMake adds a `Sphinx Domain`_ called ``cmake``, also called the
	"CMake Domain". It defines several "object" types for CMake
	documentation:

	``command``
	A CMake language command.

	``generator``
	A CMake native build system generator.
	See the `cmake(1)`_ command-line tool's ``-G`` option.

	``manual``
	A CMake manual page, like the `cmake(1)`_ manual.

	``module``
	A CMake module.
	See the `cmake-modules(7)`_ manual
	and the `include()`_ command.

	``policy``
	A CMake policy.
	See the `cmake-policies(7)`_ manual
	and the `cmake_policy()`_ command.

	``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt``
	A CMake cache, directory, global, source file, installed file, test,
	or target property, respectively. See the `cmake-properties(7)`_
	manual and the `set_property()`_ command.

	``variable``
	A CMake language variable.
	See the `cmake-variables(7)`_ manual
	and the `set()`_ command.

	Documentation objects in the CMake Domain come from two sources.
	First, the CMake extension to Sphinx transforms every document named
	with the form ``Help/<type>/<file-name>.rst`` to a domain object with
	type ``<type>``. The object name is extracted from the document title,
	which is expected to be of the form::

	<object-name>
	-------------

	and to appear at or near the top of the ``.rst`` file before any other
	lines starting in a letter, digit, or ``<``. If no such title appears
	literally in the ``.rst`` file, the object name is the ``<file-name>``.
	If a title does appear, it is expected that ``<file-name>`` is equal
	to ``<object-name>`` with any ``<`` and ``>`` characters removed.

	Second, the CMake Domain provides directives to define objects inside
	other documents:

	.. code-block:: rst

	.. command:: <command-name>

	This indented block documents <command-name>.

	.. variable:: <variable-name>

	This indented block documents <variable-name>.

	Object types for which no directive is available must be defined using
	the first approach above.

	.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
	.. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
	.. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html
	.. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html
	.. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html
	.. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html
	.. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html
	.. _`include()`: https://cmake.org/cmake/help/latest/command/include.html
	.. _`set()`: https://cmake.org/cmake/help/latest/command/set.html
	.. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html

	Cross-References
	----------------

	Sphinx uses reStructuredText interpreted text roles to provide
	cross-reference syntax. The `CMake Domain`_ provides for each
	domain object type a role of the same name to cross-reference it.
	CMake Domain roles are inline markup of the forms::

	:type:`name`
	:type:`text <name>`

	where ``type`` is the domain object type and ``name`` is the
	domain object name. In the first form the link text will be
	``name`` (or ``name()`` if the type is ``command``) and in
	the second form the link text will be the explicit ``text``.
	For example, the code:

	.. code-block:: rst

	* The :command:`list` command.
	* The :command:`list(APPEND)` sub-command.
	* The :command:`list() command <list>`.
	* The :command:`list(APPEND) sub-command <list>`.
	* The :variable:`CMAKE_VERSION` variable.
	* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.

	produces:

	* The `list()`_ command.
	* The `list(APPEND)`_ sub-command.
	* The `list() command`_.
	* The `list(APPEND) sub-command`_.
	* The `CMAKE_VERSION`_ variable.
	* The `OUTPUT_NAME_<CONFIG>`_ target property.

	Note that CMake Domain roles differ from Sphinx and reStructuredText
	convention in that the form ``a<b>``, without a space preceding ``<``,
	is interpreted as a name instead of link text with an explicit target.
	This is necessary because we use ``<placeholders>`` frequently in
	object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``,
	with a space preceding ``<``, is still interpreted as a link text
	with an explicit target.

	.. _`list()`: https://cmake.org/cmake/help/latest/command/list.html
	.. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html
	.. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html
	.. _`list() command`: https://cmake.org/cmake/help/latest/command/list.html
	.. _`CMAKE_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_VERSION.html
	.. _`OUTPUT_NAME_<CONFIG>`: https://cmake.org/cmake/help/latest/prop_tgt/OUTPUT_NAME_CONFIG.html

	Style
	-----

	Style: Section Headers
	^^^^^^^^^^^^^^^^^^^^^^

	When marking section titles, make the section decoration line as long as
	the title text. Use only a line below the title, not above. For
	example:

	.. code-block:: rst

	Title Text
	----------

	Capitalize the first letter of each non-minor word in the title.

	The section header underline character hierarchy is

	* ``#``: Manual group (part) in the master document
	* ``*``: Manual (chapter) title
	* ``=``: Section within a manual
	* ``-``: Subsection or `CMake Domain`_ object document title
	* ``^``: Subsubsection or `CMake Domain`_ object document section
	* ``"``: Paragraph or `CMake Domain`_ object document subsection

	Style: Whitespace
	^^^^^^^^^^^^^^^^^

	Use two spaces for indentation. Use two spaces between sentences in
	prose.

	Style: Line Length
	^^^^^^^^^^^^^^^^^^

	Prefer to restrict the width of lines to 75-80 columns. This is not a
	hard restriction, but writing new paragraphs wrapped at 75 columns
	allows space for adding minor content without significant re-wrapping of
	content.

	Style: Prose
	^^^^^^^^^^^^

	Use American English spellings in prose.

	Style: Starting Literal Blocks
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	Prefer to mark the start of literal blocks with ``::`` at the end of
	the preceding paragraph. In cases where the following block gets
	a ``code-block`` marker, put a single ``:`` at the end of the preceding
	paragraph.

	Style: CMake Command Signatures
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	Command signatures should be marked up as plain literal blocks, not as
	cmake ``code-blocks``.

	Signatures are separated from preceding content by a section header.
	That is, use:

	.. code-block:: rst

	... preceding paragraph.

	Normal Libraries
	^^^^^^^^^^^^^^^^

	::

	add_library(<lib> ...)

	This signature is used for ...

	Signatures of commands should wrap optional parts with square brackets,
	and should mark list of optional arguments with an ellipsis (``...``).
	Elements of the signature which are specified by the user should be
	specified with angle brackets, and may be referred to in prose using
	``inline-literal`` syntax.

	Style: Boolean Constants
	^^^^^^^^^^^^^^^^^^^^^^^^

	Use "``OFF``" and "``ON``" for boolean values which can be modified by
	the user, such as ``POSITION_INDEPENDENT_CODE``. Such properties
	may be "enabled" and "disabled". Use "``True``" and "``False``" for
	inherent values which can't be modified after being set, such as the
	``IMPORTED`` property of a build target.

	Style: Inline Literals
	^^^^^^^^^^^^^^^^^^^^^^

	Mark up references to keywords in signatures, file names, and other
	technical terms with ``inline-literal`` syntax, for example:

	.. code-block:: rst

	If ``WIN32`` is used with :command:`add_executable`, the
	:prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
	creates the file ``<name>.exe`` on Windows.

	Style: Cross-References
	^^^^^^^^^^^^^^^^^^^^^^^

	Mark up linkable references as links, including repeats.
	An alternative, which is used by wikipedia
	(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
	is to link to a reference only once per article. That style is not used
	in CMake documentation.

	Style: Referencing CMake Concepts
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	If referring to a concept which corresponds to a property, and that
	concept is described in a high-level manual, prefer to link to the
	manual section instead of the property. For example:

	.. code-block:: rst

	This command creates an :ref:`Imported Target <Imported Targets>`.

	instead of:

	.. code-block:: rst

	This command creates an :prop_tgt:`IMPORTED` target.

	The latter should be used only when referring specifically to the
	property.

	References to manual sections are not automatically created by creating
	a section, but code such as:

	.. code-block:: rst

	.. _`Imported Targets`:

	creates a suitable anchor. Use an anchor name which matches the name
	of the corresponding section. Refer to the anchor using a
	cross-reference with specified text.

	Imported Targets need the ``IMPORTED`` term marked up with care in
	particular because the term may refer to a command keyword, a target
	property, or a concept.

	Where a property, command or variable is related conceptually to others,
	by for example, being related to the buildsystem description, generator
	expressions or Qt, each relevant property, command or variable should
	link to the primary manual, which provides high-level information. Only
	particular information relating to the command should be in the
	documentation of the command.

	Style: Referencing CMake Domain Objects
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	When referring to `CMake Domain`_ objects such as properties, variables,
	commands etc, prefer to link to the target object and follow that with
	the type of object it is. For example:

	.. code-block:: rst

	Set the :prop_tgt:`AUTOMOC` target property to ``ON``.

	Instead of

	.. code-block:: rst

	Set the target property :prop_tgt:`AUTOMOC` to ``ON``.

	The ``policy`` directive is an exception, and the type us usually
	referred to before the link:

	.. code-block:: rst

	If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ...

	However, markup self-references with ``inline-literal`` syntax.
	For example, within the ``add_executable`` command documentation, use

	.. code-block:: rst

	``add_executable``

	not

	.. code-block:: rst

	:command:`add_executable`

	which is used elsewhere.

	Modules
	=======

	The ``Modules`` directory contains CMake-language ``.cmake`` module files.

	Module Documentation
	--------------------

	To document CMake module ``Modules/<module-name>.cmake``, modify
	``Help/manual/cmake-modules.7.rst`` to reference the module in the
	``toctree`` directive, in sorted order, as::

	/module/<module-name>

	Then add the module document file ``Help/module/<module-name>.rst``
	containing just the line::

	.. cmake-module:: ../../Modules/<module-name>.cmake

	The ``cmake-module`` directive will scan the module file to extract
	reStructuredText markup from comment blocks that start in ``.rst:``.
	At the top of ``Modules/<module-name>.cmake``, begin with the following
	license notice:

	::

	# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
	# file Copyright.txt or https://cmake.org/licensing for details.

	After this notice, add a BLANK line. Then, add documentation using
	a `Bracket Comment`_ of the form:

	::

	#[=======================================================================[.rst:
	<module-name>
	-------------

	<reStructuredText documentation of module>
	#]=======================================================================]

	Any number of ``=`` may be used in the opening and closing brackets
	as long as they match. Content on the line containing the closing
	bracket is excluded if and only if the line starts in ``#``.

	Additional such ``.rst:`` comments may appear anywhere in the module file.
	All such comments must start with ``#`` in the first column.

	For example, a ``Findxxx.cmake`` module may contain:

	::

	# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
	# file Copyright.txt or https://cmake.org/licensing for details.

	#[=======================================================================[.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?
	#]=======================================================================]

	<code>

	#[=======================================================================[.rst:
	.. command:: xxx_do_something

	This command does something for Xxx::

	xxx_do_something(some arguments)
	#]=======================================================================]
	macro(xxx_do_something)
	<code>
	endmacro()

	Test the documentation formatting by running
	``cmake --help-module <module-name>``, and also 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-name>.rst``
	file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.

	.. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment