diff options
author | Matthew Woehlke <matthew.woehlke@kitware.com> | 2023-02-24 20:01:14 (GMT) |
---|---|---|
committer | Matthew Woehlke <matthew.woehlke@kitware.com> | 2023-03-03 22:05:02 (GMT) |
commit | 74e3c1d313616b5faf83ff423c8e8ef3f2010a41 (patch) | |
tree | 7f24ecc7db552a3e658a742848cdc0f408c06c7a /Help/dev | |
parent | c09b7604841448b0c949e5c98ea791c9dc9d477e (diff) | |
download | CMake-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.rst | 95 |
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 ^^^^^^^^^^^^^^^^^^^^^^^^ |