Merge topic 'doc-section-header-convention'
793b64e4Help: Document section header underline hierarchy in cmake-developer.705bd31abHelp: Organize documentation style sections in cmake-developer.7eaafe756Help: Add documentation style section headers to cmake-developer.74207b3a3Help: Use "^^^^" for subsubsection headers
This commit is contained in:
Brad King
CMake Topic Stage
commit
02d540c758
|
|
@ -18,7 +18,7 @@ setting is available the ``OLD`` behavior is assumed and a warning is
|
|||
produced requesting that the policy be set.
|
||||
|
||||
Setting Policies by CMake Version
|
||||
'''''''''''''''''''''''''''''''''
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
|
||||
behavior. While setting policies individually is supported, we
|
||||
|
|
@ -40,7 +40,7 @@ Note that the :command:`cmake_minimum_required(VERSION)`
|
|||
command implicitly calls ``cmake_policy(VERSION)`` too.
|
||||
|
||||
Setting Policies Explicitly
|
||||
'''''''''''''''''''''''''''
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -54,7 +54,7 @@ one may fix the project to work with the new behavior and set the
|
|||
policy state to ``NEW``.
|
||||
|
||||
Checking Policy Settings
|
||||
''''''''''''''''''''''''
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
|
|||
policy is set, and empty otherwise.
|
||||
|
||||
CMake Policy Stack
|
||||
''''''''''''''''''
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
CMake keeps policy settings on a stack, so changes made by the
|
||||
cmake_policy command affect only the top of the stack. A new entry on
|
||||
|
|
|
|||
|
|
@ -551,7 +551,7 @@ exporting see the :manual:`cmake-packages(7)` manual.
|
|||
.. _`Include Directories and Usage Requirements`:
|
||||
|
||||
Include Directories and Usage Requirements
|
||||
''''''''''''''''''''''''''''''''''''''''''
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Include directories require some special consideration when specified as usage
|
||||
requirements and when used with generator expressions. The
|
||||
|
|
|
|||
|
|
@ -465,15 +465,66 @@ with an explicit target.
|
|||
Style
|
||||
-----
|
||||
|
||||
1)
|
||||
Command signatures should be marked up as plain literal blocks, not as
|
||||
cmake ``code-blocks``.
|
||||
Style: Section Headers
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
2)
|
||||
Signatures are separated from preceding content by a horizontal
|
||||
line. That is, use:
|
||||
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
|
||||
.. 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 horizontal
|
||||
line. That is, use:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
... preceding paragraph.
|
||||
|
||||
|
|
@ -485,148 +536,124 @@ Style
|
|||
|
||||
This signature is used for ...
|
||||
|
||||
3)
|
||||
Use "``OFF``" and "``ON``" for boolean values which can be modified by
|
||||
the user, such as :prop_tgt:`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
|
||||
:prop_tgt:`IMPORTED` property of a build target.
|
||||
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.
|
||||
|
||||
4)
|
||||
Use two spaces for indentation. Use two spaces between sentences in
|
||||
prose.
|
||||
Style: Boolean Constants
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
5)
|
||||
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.
|
||||
Use "``OFF``" and "``ON``" for boolean values which can be modified by
|
||||
the user, such as :prop_tgt:`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
|
||||
:prop_tgt:`IMPORTED` property of a build target.
|
||||
|
||||
6)
|
||||
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: Inline Literals
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
7)
|
||||
Mark up self-references with ``inline-literal`` syntax. For example,
|
||||
within the add_executable command documentation, use
|
||||
Mark up references to keywords in signatures, file names, and other
|
||||
technical terms with ``inline-literal`` syntax, for example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
``add_executable``
|
||||
|
||||
not
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
:command:`add_executable`
|
||||
|
||||
which is used elsewhere.
|
||||
|
||||
8)
|
||||
Mark up all other 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.
|
||||
|
||||
9)
|
||||
Mark up references to keywords in signatures, file names, and other
|
||||
technical terms with ``inline-literl`` syntax, for example:
|
||||
|
||||
.. code-block:: rst
|
||||
.. 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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
10)
|
||||
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:
|
||||
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.
|
||||
|
||||
.. code-block:: rst
|
||||
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:
|
||||
instead of:
|
||||
|
||||
.. code-block:: rst
|
||||
.. code-block:: rst
|
||||
|
||||
This command creates an :prop_tgt:`IMPORTED` target.
|
||||
|
||||
The latter should be used only when referring specifically to the
|
||||
property.
|
||||
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:
|
||||
References to manual sections are not automatically created by creating
|
||||
a section, but code such as:
|
||||
|
||||
.. code-block:: rst
|
||||
.. 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.
|
||||
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
|
||||
(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
|
||||
concept (:ref:`Imported Targets`).
|
||||
Imported Targets need the ``IMPORTED`` term marked up with care in
|
||||
particular because the term may refer to a command keyword
|
||||
(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
|
||||
concept (:ref:`Imported Targets`).
|
||||
|
||||
11)
|
||||
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.
|
||||
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.
|
||||
|
||||
12)
|
||||
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:
|
||||
Style: Referencing CMake Domain Objects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: rst
|
||||
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:
|
||||
|
||||
Title Text
|
||||
----------
|
||||
|
||||
Capitalize the first letter of each non-minor word in the title.
|
||||
|
||||
13)
|
||||
When referring to 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
|
||||
.. code-block:: rst
|
||||
|
||||
Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
|
||||
|
||||
Instead of
|
||||
Instead of
|
||||
|
||||
.. code-block:: rst
|
||||
.. 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:
|
||||
The ``policy`` directive is an exception, and the type us usually
|
||||
referred to before the link:
|
||||
|
||||
.. code-block:: rst
|
||||
.. code-block:: rst
|
||||
|
||||
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
|
||||
|
||||
14)
|
||||
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.
|
||||
However, markup self-references with ``inline-literal`` syntax.
|
||||
For example, within the :command:`add_executable` command
|
||||
documentation, use
|
||||
|
||||
15)
|
||||
Use American English spellings in prose.
|
||||
.. code-block:: rst
|
||||
|
||||
``add_executable``
|
||||
|
||||
not
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
:command:`add_executable`
|
||||
|
||||
which is used elsewhere.
|
||||
|
||||
Modules
|
||||
=======
|
||||
|
|
@ -808,7 +835,7 @@ Documentation`_ section above.
|
|||
|
||||
|
||||
Standard Variable Names
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For a ``FindXxx.cmake`` module that takes the approach of setting
|
||||
variables (either instead of or in addition to creating imported
|
||||
|
|
@ -914,7 +941,7 @@ them.
|
|||
|
||||
|
||||
A Sample Find Module
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
We will describe how to create a simple find module for a library
|
||||
``Foo``.
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ CMake. Target dependencies may be added to that custom target by adding them
|
|||
to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
|
||||
|
||||
AUTOMOC
|
||||
'''''''
|
||||
^^^^^^^
|
||||
|
||||
The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)`
|
||||
inspects the C++ files in the target to determine if they require ``moc`` to
|
||||
|
|
@ -84,7 +84,7 @@ variable may be populated to pre-set the options for all following targets.
|
|||
.. _`Qt AUTOUIC`:
|
||||
|
||||
AUTOUIC
|
||||
'''''''
|
||||
^^^^^^^
|
||||
|
||||
The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)`
|
||||
inspects the C++ files in the target to determine if they require ``uic`` to
|
||||
|
|
@ -147,7 +147,7 @@ result of linking with the :prop_tgt:`IMPORTED` target:
|
|||
.. _`Qt AUTORCC`:
|
||||
|
||||
AUTORCC
|
||||
'''''''
|
||||
^^^^^^^
|
||||
|
||||
The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)`
|
||||
creates rules to execute ``rcc`` at the appropriate time on source files
|
||||
|
|
|
|||
Loading…
Reference in New Issue