summaryrefslogtreecommitdiffstats
path: root/Help/dev
diff options
context:
space:
mode:
authorMatthew Woehlke <matthew.woehlke@kitware.com>2023-02-24 20:01:14 (GMT)
committerMatthew Woehlke <matthew.woehlke@kitware.com>2023-03-03 22:05:02 (GMT)
commit74e3c1d313616b5faf83ff423c8e8ef3f2010a41 (patch)
tree7f24ecc7db552a3e658a742848cdc0f408c06c7a /Help/dev
parentc09b7604841448b0c949e5c98ea791c9dc9d477e (diff)
downloadCMake-74e3c1d313616b5faf83ff423c8e8ef3f2010a41.zip
CMake-74e3c1d313616b5faf83ff423c8e8ef3f2010a41.tar.gz
CMake-74e3c1d313616b5faf83ff423c8e8ef3f2010a41.tar.bz2
Utilities/Sphinx: Add a directive to document command signatures
Add a `signature` directive to offer a CMake version of Sphinx's `function` directive, similar to that found in other domains (py, cpp, etc.). Like others, this takes one or more signatures as arguments and creates dt/dd nodes from the signatures and the directive contents.
Diffstat (limited to 'Help/dev')
-rw-r--r--Help/dev/documentation.rst95
1 files changed, 82 insertions, 13 deletions
diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index cd9f784..a340739 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -241,6 +241,69 @@ Document a "genex" object:
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
^^^^^^^^^^^^^^^^^^^^^^
@@ -374,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
@@ -387,17 +450,23 @@ That is, use:
Normal Libraries
^^^^^^^^^^^^^^^^
- ::
-
+ .. signature::
add_library(<lib> ...)
- This signature is used for ...
+ This signature is used for ...
+
+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 (``...``).
-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.
+The ``signature`` directive may be used multiple times for different
+signatures of the same command.
Style: Boolean Constants
^^^^^^^^^^^^^^^^^^^^^^^^