diff options
Diffstat (limited to 'Help/dev/documentation.rst')
| -rw-r--r-- | Help/dev/documentation.rst | 215 |
1 files changed, 177 insertions, 38 deletions
diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index db92022089..c6fb7a653c 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -168,46 +168,175 @@ 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> + + This indented block documents <command-name>. + +The directive requires a single argument, the command name. + +``envvar`` directive +^^^^^^^^^^^^^^^^^^^^ + +Document an "envvar" object: .. code-block:: rst - .. command:: <command-name> + .. envvar:: <envvar-name> + + This indented block documents <envvar-name>. + +The directive requires a single argument, the environment variable name. - This indented block documents <command-name>. +``genex`` directive +^^^^^^^^^^^^^^^^^^^ - .. envvar:: <envvar-name> +Document a "genex" object: - This indented block documents <envvar-name>. +.. code-block:: rst .. genex:: <genex-name> This indented block documents <genex-name>. +The directive requires a single argument, the generator expression name. + +The optional ``:target:`` option allows a custom target name to be specified. +Because this will affect the ability to reference the "genex" object using the +``:genex:`` role, this option should be used very sparingly. + +``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 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, however + they can be globally referenced using e.g. ``:command:`string(APPEND)```. + +Although whitespace in the signature is not preserved, by default, line breaks +are suppressed inside of square- or angle-brackets. This behavior can be +controlled using the ``:break:`` option; note, however, that there is no way +to *force* a line break. The default value is 'smart'. Allowable values are: + + ``all`` + Allow line breaks at any whitespace. + + ``smart`` (default) + Allow line breaks at whitespace, except between matched square- or + angle-brackets. For example, if a signature contains the text + ``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed + after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``. + + ``verbatim`` + Allow line breaks only where the source document contains a newline. + +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 @@ -266,6 +395,10 @@ object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, with a space preceding ``<``, is still interpreted as a link text with an explicit target. +Additionally, the ``cref`` role may be used to create references +to local targets that have literal styling. This is especially +useful for referencing a subcommand in the command's documentation. + .. _`list()`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html @@ -329,11 +462,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 +475,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 ^^^^^^^^^^^^^^^^^^^^^^^^ |