Merge topic 'improve-doc-signatures'

533ebb072b Help: Use signature directive for string command
cd33f461a6 Help: Use signature directive for cmake_language command
74e3c1d313 Utilities/Sphinx: Add a directive to document command signatures
c09b760484 Utilities/Sphinx: Drop commented-out code from cmake domain impl
6e85ad7f8b Help/dev: Add per-directive sections in CMake Documentation Guide

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8243

1 files changed, 152 insertions, 38 deletions

diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index db92022..a340739 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -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::
-
- <object-name>
- -------------
-
-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``.
-
-Second, the CMake Domain provides directives to define objects inside
-other documents:
+Documentation objects in the CMake Domain come from two sources:
+
+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::
+
+    <object-name>
+    -------------
+
+   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>.
+The directive requires a single argument, the command name.
 
- .. envvar:: <envvar-name>
+``envvar`` directive
+^^^^^^^^^^^^^^^^^^^^
+
+Document an "envvar" object:
+
+.. code-block:: rst
 
-  This indented block documents <envvar-name>.
+  .. 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 ...
+
+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
 ^^^^^^^^^^^^^^^^^^^^^^^^