mirror of
https://github.com/Kitware/CMake.git
synced 2026-03-03 05:08:47 -06:00
Merge topic 'improve-doc-signatures'
533ebb072bHelp: Use signature directive for string commandcd33f461a6Help: Use signature directive for cmake_language command74e3c1d313Utilities/Sphinx: Add a directive to document command signaturesc09b760484Utilities/Sphinx: Drop commented-out code from cmake domain impl6e85ad7f8bHelp/dev: Add per-directive sections in CMake Documentation Guide Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !8243
This commit is contained in:
Brad King
@@ -168,46 +168,154 @@ documentation:
|
||||
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::
|
||||
Documentation objects in the CMake Domain come from two sources:
|
||||
|
||||
<object-name>
|
||||
-------------
|
||||
1. 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::
|
||||
|
||||
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,
|
||||
or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the
|
||||
``genex-name``.
|
||||
<object-name>
|
||||
-------------
|
||||
|
||||
Second, the CMake Domain provides directives to define objects inside
|
||||
other documents:
|
||||
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,
|
||||
or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the
|
||||
``genex-name``.
|
||||
|
||||
2. `CMake Domain directives`_ may be used in documents to explicitly define
|
||||
some object types:
|
||||
|
||||
* `command directive`_
|
||||
* `envvar directive`_
|
||||
* `genex directive`_
|
||||
* `variable directive`_
|
||||
|
||||
Object types for which no directive is available must be defined using
|
||||
the document transform above.
|
||||
|
||||
CMake Domain Directives
|
||||
-----------------------
|
||||
|
||||
The CMake Domain provides the following directives.
|
||||
|
||||
``command`` directive
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Document a "command" object:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. command:: <command-name>
|
||||
.. command:: <command-name>
|
||||
|
||||
This indented block documents <command-name>.
|
||||
This indented block documents <command-name>.
|
||||
|
||||
.. envvar:: <envvar-name>
|
||||
The directive requires a single argument, the command name.
|
||||
|
||||
This indented block documents <envvar-name>.
|
||||
``envvar`` directive
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Document an "envvar" object:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. envvar:: <envvar-name>
|
||||
|
||||
This indented block documents <envvar-name>.
|
||||
|
||||
The directive requires a single argument, the environment variable name.
|
||||
|
||||
``genex`` directive
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Document a "genex" object:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. genex:: <genex-name>
|
||||
|
||||
This indented block documents <genex-name>.
|
||||
|
||||
The directive requires a single argument, the generator expression name.
|
||||
|
||||
``signature`` directive
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Document `CMake Command Signatures <Style: CMake Command Signatures_>`_
|
||||
within a ``Help/command/<command-name>.rst`` document.
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. signature:: <command-name>(<signature>)
|
||||
|
||||
This indented block documents one or more signatures of a CMake command.
|
||||
|
||||
The ``signature`` directive requires one argument, the signature summary:
|
||||
|
||||
* One or more signatures must immediately follow the ``::``.
|
||||
The first signature may optionally be placed on the same line.
|
||||
A blank line following the ``signature`` directive will result in a
|
||||
documentation generation error: ``1 argument(s) required, 0 supplied``.
|
||||
|
||||
* Signatures may be split across multiple lines, but the final ``)`` of each
|
||||
signature must be the last character on its line.
|
||||
|
||||
* Blank lines between signatures are not allowed. (Content after a blank line
|
||||
is treated as part of the description.)
|
||||
|
||||
* Whitespace in signatures is not preserved. To document a complex signature,
|
||||
abbreviate it in the ``signature`` directive argument and specify the full
|
||||
signature in a ``code-block`` in the description.
|
||||
|
||||
The ``signature`` directive generates a document-local hyperlink target
|
||||
for each signature:
|
||||
|
||||
* Default target names are automatically extracted from leading "keyword"
|
||||
arguments in the signatures, where a keyword is any sequence of
|
||||
non-space starting with a letter. For example, the signature
|
||||
``string(REGEX REPLACE <match-regex> ...)`` generates the target
|
||||
``REGEX REPLACE``, similar to ``.. _`REGEX REPLACE`:``.
|
||||
|
||||
* Custom target names may be specified using a ``:target:`` option.
|
||||
For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. signature::
|
||||
cmake_path(GET <path-var> ROOT_NAME <out-var>)
|
||||
cmake_path(GET <path-var> ROOT_PATH <out-var>)
|
||||
:target:
|
||||
GET ROOT_NAME
|
||||
GET ROOT_PATH
|
||||
|
||||
Provide a custom target name for each signature, one per line.
|
||||
The first target may optionally be placed on the same line as ``:target:``.
|
||||
|
||||
* If a target name is already in use earlier in the document, no hyperlink
|
||||
target will be generated.
|
||||
|
||||
* The targets may be referenced from within the same document using
|
||||
```REF`_`` or ```TEXT <REF_>`_`` syntax. Like reStructuredText section
|
||||
headers, the targets do not work with Sphinx ``:ref:`` syntax.
|
||||
|
||||
The directive treats its content as the documentation of the signature(s).
|
||||
Indent the signature documentation accordingly.
|
||||
|
||||
``variable`` directive
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Document a "variable" object:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. 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.
|
||||
The directive requires a single argument, the variable name.
|
||||
|
||||
.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
|
||||
.. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
|
||||
@@ -329,11 +437,11 @@ 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:
|
||||
A ``Help/command/<command-name>.rst`` document defines one ``command``
|
||||
object in the `CMake Domain`_, but some commands have multiple signatures.
|
||||
Use the CMake Domain's `signature directive`_ to document each signature.
|
||||
Separate signatures from preceding content by a section header.
|
||||
For example:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
@@ -342,17 +450,23 @@ That is, use:
|
||||
Normal Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
.. signature::
|
||||
add_library(<lib> ...)
|
||||
|
||||
This signature is used for ...
|
||||
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.
|
||||
Use the following conventions in command signature documentation:
|
||||
|
||||
* Use an angle-bracket ``<placeholder>`` for arguments to be specified
|
||||
by the caller. Refer to them in prose using
|
||||
`inline literal <Style: Inline Literals_>`_ syntax.
|
||||
|
||||
* Wrap optional parts with square brackets.
|
||||
|
||||
* Mark repeatable parts with a trailing ellipsis (``...``).
|
||||
|
||||
The ``signature`` directive may be used multiple times for different
|
||||
signatures of the same command.
|
||||
|
||||
Style: Boolean Constants
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user