kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Add documentation style section headers to cmake-developer.7 

Give the style guides titles instead of numbers so we can link to them.
This commit is contained in:
Brad King 2014-06-02 13:58:01 -04:00
parent 4207b3a3bb
commit eaafe756d5
1 changed files with 132 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
Help/manual/cmake-developer.7.rst
View File

@ -465,15 +465,16 @@ with an explicit target.
Style Style
----- -----
1) Style: Command Signatures
Command signatures should be marked up as plain literal blocks, not as ^^^^^^^^^^^^^^^^^^^^^^^^^
cmake ``code-blocks``.
2) Command signatures should be marked up as plain literal blocks, not as
Signatures are separated from preceding content by a horizontal cmake ``code-blocks``.
line. That is, use:
.. code-block:: rst Signatures are separated from preceding content by a horizontal
line. That is, use:
.. code-block:: rst
... preceding paragraph. ... preceding paragraph.
@ -485,148 +486,169 @@ Style
This signature is used for ... This signature is used for ...
3) Style: Boolean Constants
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.
4) Use "``OFF``" and "``ON``" for boolean values which can be modified by
Use two spaces for indentation. Use two spaces between sentences in the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
prose. 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.
5) Style: Whitespace
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.
6) Use two spaces for indentation. Use two spaces between sentences in
Prefer to restrict the width of lines to 75-80 columns. This is not a prose.
hard restriction, but writing new paragraphs wrapped at 75 columns
allows space for adding minor content without significant re-wrapping of
content.
7) Style: Starting Literal Blocks
Mark up self-references with ``inline-literal`` syntax. For example, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
within the add_executable command documentation, use
.. code-block:: rst 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: 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: Document Self-References
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
.. code-block:: rst
``add_executable`` ``add_executable``
not not
.. code-block:: rst .. code-block:: rst
:command:`add_executable` :command:`add_executable`
which is used elsewhere. which is used elsewhere.
8) Style: Linkable References
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 all other linkable references as links, including repeats. An
Mark up references to keywords in signatures, file names, and other alternative, which is used by wikipedia (`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
technical terms with ``inline-literl`` syntax, for example: is to link to a reference only once per article. That style is not used
in CMake documentation.
.. code-block:: rst Style: Technical Terms
^^^^^^^^^^^^^^^^^^^^^^
Mark up references to keywords in signatures, file names, and other
technical terms with ``inline-literl`` syntax, for example:
.. code-block:: rst
If ``WIN32`` is used with :command:`add_executable`, the If ``WIN32`` is used with :command:`add_executable`, the
:prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
creates the file ``<name>.exe`` on Windows. creates the file ``<name>.exe`` on Windows.
Style: Referencing Concepts
^^^^^^^^^^^^^^^^^^^^^^^^^^^
10) If referring to a concept which corresponds to a property, and that
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
concept is described in a high-level manual, prefer to link to the manual section instead of the property. For example:
manual section instead of the property. For example:
.. code-block:: rst .. code-block:: rst
This command creates an :ref:`Imported Target <Imported Targets>`. 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. This command creates an :prop_tgt:`IMPORTED` target.
The latter should be used only when referring specifically to the The latter should be used only when referring specifically to the
property. property.
References to manual sections are not automatically created by creating References to manual sections are not automatically created by creating
a section, but code such as: a section, but code such as:
.. code-block:: rst .. code-block:: rst
.. _`Imported Targets`: .. _`Imported Targets`:
creates a suitable anchor. Use an anchor name which matches the name creates a suitable anchor. Use an anchor name which matches the name
of the corresponding section. Refer to the anchor using a of the corresponding section. Refer to the anchor using a
cross-reference with specified text. cross-reference with specified text.
Imported Targets need the ``IMPORTED`` term marked up with care in Imported Targets need the ``IMPORTED`` term marked up with care in
particular because the term may refer to a command keyword particular because the term may refer to a command keyword
(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a (``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
concept (:ref:`Imported Targets`). concept (:ref:`Imported Targets`).
11) Where a property, command or variable is related conceptually to others,
Where a property, command or variable is related conceptually to others, by for example, being related to the buildsystem description, generator
by for example, being related to the buildsystem description, generator expressions or Qt, each relevant property, command or variable should
expressions or Qt, each relevant property, command or variable should link to the primary manual, which provides high-level information. Only
link to the primary manual, which provides high-level information. Only particular information relating to the command should be in the
particular information relating to the command should be in the documentation of the command.
documentation of the command.
12) Style: Section Titles
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 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 Title Text
---------- ----------
Capitalize the first letter of each non-minor word in the title. Capitalize the first letter of each non-minor word in the title.
13) Style: Referencing CMake Domain Objects
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 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
Set the :prop_tgt:`AUTOMOC` target property to ``ON``. 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``. Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
The ``policy`` directive is an exception, and the type us usually The ``policy`` directive is an exception, and the type us usually
referred to before the link: referred to before the link:
.. code-block:: rst .. code-block:: rst
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
14) Style: Command Signature Markup
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.
15) Signatures of commands should wrap optional parts with square brackets,
Use American English spellings in prose. 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: Prose
^^^^^^^^^^^^
Use American English spellings in prose.
Modules Modules
======= =======