mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-12 17:19:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'improve-doc-signatures'

Browse Source 
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
This commit is contained in:
Brad King
2023-03-07 13:49:06 +00:00
committed by Kitware Robot
parent 2e8e5c2cf0 533ebb072b
commit 3d6075da4d
8 changed files with 706 additions and 572 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/cmake_language.rst
+146 -159
View File
@@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands.
Calling Commands
^^^^^^^^^^^^^^^^
.. _CALL:
.. code-block:: cmake
.. signature::
cmake_language(CALL <command> [<arg>...])
Calls the named ``<command>`` with the given arguments (if any).
For example, the code:
Calls the named ``<command>`` with the given arguments (if any).
For example, the code:
.. code-block:: cmake
.. code-block:: cmake
set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")
set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to
is equivalent to
.. code-block:: cmake
.. code-block:: cmake
message(STATUS "Hello World!")
message(STATUS "Hello World!")
.. note::
To ensure consistency of the code, the following commands are not allowed:
.. note::
To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
* ``macro`` / ``endmacro``
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
* ``macro`` / ``endmacro``
Evaluating Code
^^^^^^^^^^^^^^^
.. _EVAL:
.. code-block:: cmake
.. signature::
cmake_language(EVAL CODE <code>...)
:target: EVAL
Evaluates the ``<code>...`` as CMake code.
Evaluates the ``<code>...`` as CMake code.
For example, the code:
For example, the code:
.. code-block:: cmake
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
cmake_language(EVAL CODE "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
cmake_language(EVAL CODE "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
is equivalent to
is equivalent to
.. code-block:: cmake
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
Deferring Calls
^^^^^^^^^^^^^^^
.. versionadded:: 3.19
.. _DEFER:
.. code-block:: cmake
.. signature::
cmake_language(DEFER <options>... CALL <command> [<arg>...])
Schedules a call to the named ``<command>`` with the given arguments (if any)
to occur at a later time. By default, deferred calls are executed as if
written at the end of the current directory's ``CMakeLists.txt`` file,
except that they run even after a :command:`return` call. Variable
references in arguments are evaluated at the time the deferred call is
executed.
Schedules a call to the named ``<command>`` with the given arguments (if any)
to occur at a later time. By default, deferred calls are executed as if
written at the end of the current directory's ``CMakeLists.txt`` file,
except that they run even after a :command:`return` call. Variable
references in arguments are evaluated at the time the deferred call is
executed.
The options are:
The options are:
``DIRECTORY <dir>``
Schedule the call for the end of the given directory instead of the
current directory. The ``<dir>`` may reference either a source
directory or its corresponding binary directory. Relative paths are
treated as relative to the current source directory.
``DIRECTORY <dir>``
Schedule the call for the end of the given directory instead of the
current directory. The ``<dir>`` may reference either a source
directory or its corresponding binary directory. Relative paths are
treated as relative to the current source directory.
The given directory must be known to CMake, being either the top-level
directory or one added by :command:`add_subdirectory`. Furthermore,
the given directory must not yet be finished processing. This means
it can be the current directory or one of its ancestors.
The given directory must be known to CMake, being either the top-level
directory or one added by :command:`add_subdirectory`. Furthermore,
the given directory must not yet be finished processing. This means
it can be the current directory or one of its ancestors.
``ID <id>``
Specify an identification for the deferred call.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID <id>``
Specify an identification for the deferred call.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID_VAR <var>``
Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification
will be generated and the generated id will start with an underscore (``_``).
``ID_VAR <var>``
Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification
will be generated and the generated id will start with an underscore (``_``).
The currently scheduled list of deferred calls may be retrieved:
The currently scheduled list of deferred calls may be retrieved:
.. code-block:: cmake
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids. The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created. The ``DIRECTORY``
option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope will
be returned.
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids. The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created. The ``DIRECTORY``
option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope
will be returned.
Details of a specific call may be retrieved from its id:
Details of a specific call may be retrieved from its id:
.. code-block:: cmake
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id,
this retrieves the first one. If no call is scheduled with the given id in
the specified ``DIRECTORY`` scope (or the current directory scope if no
``DIRECTORY`` option is given), this stores an empty string in the variable.
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id,
this retrieves the first one. If no call is scheduled with the given id in
the specified ``DIRECTORY`` scope (or the current directory scope if no
``DIRECTORY`` option is given), this stores an empty string in the variable.
Deferred calls may be canceled by their id:
Deferred calls may be canceled by their id:
.. code-block:: cmake
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
This cancels all deferred calls matching any of the given ids in the specified
``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
is given). Unknown ids are silently ignored.
This cancels all deferred calls matching any of the given ids in the specified
``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
is given). Unknown ids are silently ignored.
Deferred Call Examples
""""""""""""""""""""""
@@ -229,8 +221,6 @@ also prints::
Deferred Message 1
Deferred Message 2
.. _SET_DEPENDENCY_PROVIDER:
.. _dependency_providers:
Dependency Providers
@@ -241,51 +231,50 @@ Dependency Providers
.. note:: A high-level introduction to this feature can be found in the
:ref:`Using Dependencies Guide <dependency_providers_overview>`.
.. code-block:: cmake
.. signature::
cmake_language(SET_DEPENDENCY_PROVIDER <command>
SUPPORTED_METHODS <methods>...)
When a call is made to :command:`find_package` or
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the ``<methods>`` specified when the provider
was set, CMake calls the provider's ``<command>`` with a set of
method-specific arguments. If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider
is set, the built-in :command:`find_package` or
:command:`FetchContent_MakeAvailable` implementation is used to fulfill
the request in the usual way.
When a call is made to :command:`find_package` or
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the ``<methods>`` specified when the provider
was set, CMake calls the provider's ``<command>`` with a set of
method-specific arguments. If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider
is set, the built-in :command:`find_package` or
:command:`FetchContent_MakeAvailable` implementation is used to fulfill
the request in the usual way.
One or more of the following values can be specified for the ``<methods>``
when setting the provider:
One or more of the following values can be specified for the ``<methods>``
when setting the provider:
``FIND_PACKAGE``
The provider command accepts :command:`find_package` requests.
``FIND_PACKAGE``
The provider command accepts :command:`find_package` requests.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The provider command accepts :command:`FetchContent_MakeAvailable`
requests. It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The provider command accepts :command:`FetchContent_MakeAvailable`
requests. It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go.
Only one provider can be set at any point in time. If a provider is already
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
provider replaces the previously set one. The specified ``<command>`` must
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
As a special case, providing an empty string for the ``<command>`` and no
``<methods>`` will discard any previously set provider.
Only one provider can be set at any point in time. If a provider is already
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
provider replaces the previously set one. The specified ``<command>`` must
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
As a special case, providing an empty string for the ``<command>`` and no
``<methods>`` will discard any previously set provider.
The dependency provider can only be set while processing one of the files
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
Thus, dependency providers can only be set as part of the first call to
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error.
The dependency provider can only be set while processing one of the files
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
Thus, dependency providers can only be set as part of the first call to
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error.
.. note::
The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
the use of such a file should always be the user's choice.
.. note::
The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
the use of such a file should always be the user's choice.
Provider commands
"""""""""""""""""
@@ -499,23 +488,21 @@ Getting current message log level
.. versionadded:: 3.25
.. _GET_MESSAGE_LOG_LEVEL:
.. _query_message_log_level:
.. code-block:: cmake
.. signature::
cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
Writes the current :command:`message` logging level
into the given ``<output_variable>``.
Writes the current :command:`message` logging level
into the given ``<output_variable>``.
See :command:`message` for the possible logging levels.
See :command:`message` for the possible logging levels.
The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.
Help/command/string.rst
+288 -362
View File
@@ -45,16 +45,16 @@ Synopsis
`JSON`_
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
{:ref:`GET <JSON_GET>` | :ref:`TYPE <JSON_TYPE>` | :ref:`LENGTH <JSON_LENGTH>` | :ref:`REMOVE <JSON_REMOVE>`}
{`GET <JSON GET_>`_ | `TYPE <JSON TYPE_>`_ | `LENGTH <JSON LENGTH_>`_ | `REMOVE <JSON REMOVE_>`_}
<json-string> <member|index> [<member|index> ...])
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
:ref:`MEMBER <JSON_MEMBER>` <json-string>
`MEMBER <JSON MEMBER_>`_ <json-string>
[<member|index> ...] <index>)
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
:ref:`SET <JSON_SET>` <json-string>
`SET <JSON SET_>`_ <json-string>
<member|index> [<member|index> ...] <value>)
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
:ref:`EQUAL <JSON_EQUAL>` <json-string1> <json-string2>)
`EQUAL <JSON EQUAL_>`_ <json-string1> <json-string2>)
Search and Replace
^^^^^^^^^^^^^^^^^^
@@ -62,75 +62,60 @@ Search and Replace
Search and Replace With Plain Strings
"""""""""""""""""""""""""""""""""""""
.. _FIND:
.. code-block:: cmake
.. signature::
string(FIND <string> <substring> <output_variable> [REVERSE])
Return the position where the given ``<substring>`` was found in
the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will
search for the position of the last occurrence of the specified
``<substring>``. If the ``<substring>`` is not found, a position of -1 is
returned.
Return the position where the given ``<substring>`` was found in
the supplied ``<string>``. If the ``REVERSE`` flag was used, the command
will search for the position of the last occurrence of the specified
``<substring>``. If the ``<substring>`` is not found, a position of -1 is
returned.
The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
The index stored in ``<output_variable>`` will also be counted in bytes,
so strings containing multi-byte characters may lead to unexpected results.
.. _REPLACE:
.. code-block:: cmake
The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
The index stored in ``<output_variable>`` will also be counted in bytes,
so strings containing multi-byte characters may lead to unexpected results.
.. signature::
string(REPLACE <match_string>
<replace_string> <output_variable>
<input> [<input>...])
Replace all occurrences of ``<match_string>`` in the ``<input>``
with ``<replace_string>`` and store the result in the ``<output_variable>``.
Replace all occurrences of ``<match_string>`` in the ``<input>``
with ``<replace_string>`` and store the result in the ``<output_variable>``.
Search and Replace With Regular Expressions
"""""""""""""""""""""""""""""""""""""""""""
.. _`REGEX MATCH`:
.. code-block:: cmake
.. signature::
string(REGEX MATCH <regular_expression>
<output_variable> <input> [<input>...])
Match the ``<regular_expression>`` once and store the match in the
``<output_variable>``.
All ``<input>`` arguments are concatenated before matching.
Regular expressions are specified in the subsection just below.
.. _`REGEX MATCHALL`:
.. code-block:: cmake
Match the ``<regular_expression>`` once and store the match in the
``<output_variable>``.
All ``<input>`` arguments are concatenated before matching.
Regular expressions are specified in the subsection just below.
.. signature::
string(REGEX MATCHALL <regular_expression>
<output_variable> <input> [<input>...])
Match the ``<regular_expression>`` as many times as possible and store the
matches in the ``<output_variable>`` as a list.
All ``<input>`` arguments are concatenated before matching.
.. _`REGEX REPLACE`:
.. code-block:: cmake
Match the ``<regular_expression>`` as many times as possible and store the
matches in the ``<output_variable>`` as a list.
All ``<input>`` arguments are concatenated before matching.
.. signature::
string(REGEX REPLACE <regular_expression>
<replacement_expression> <output_variable>
<input> [<input>...])
Match the ``<regular_expression>`` as many times as possible and substitute
the ``<replacement_expression>`` for the match in the output.
All ``<input>`` arguments are concatenated before matching.
Match the ``<regular_expression>`` as many times as possible and substitute
the ``<replacement_expression>`` for the match in the output.
All ``<input>`` arguments are concatenated before matching.
The ``<replacement_expression>`` may refer to parenthesis-delimited
subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that
two backslashes (``\\1``) are required in CMake code to get a backslash
through argument parsing.
The ``<replacement_expression>`` may refer to parenthesis-delimited
subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that
two backslashes (``\\1``) are required in CMake code to get a backslash
through argument parsing.
.. _`Regex Specification`:
@@ -201,130 +186,100 @@ newlines, and backslashes (respectively) to pass in a regex. For example:
Manipulation
^^^^^^^^^^^^
.. _APPEND:
.. code-block:: cmake
.. signature::
string(APPEND <string_variable> [<input>...])
.. versionadded:: 3.4
.. versionadded:: 3.4
Append all the ``<input>`` arguments to the string.
.. _PREPEND:
.. code-block:: cmake
Append all the ``<input>`` arguments to the string.
.. signature::
string(PREPEND <string_variable> [<input>...])
.. versionadded:: 3.10
.. versionadded:: 3.10
Prepend all the ``<input>`` arguments to the string.
.. _CONCAT:
.. code-block:: cmake
Prepend all the ``<input>`` arguments to the string.
.. signature::
string(CONCAT <output_variable> [<input>...])
Concatenate all the ``<input>`` arguments together and store
the result in the named ``<output_variable>``.
.. _JOIN:
.. code-block:: cmake
Concatenate all the ``<input>`` arguments together and store
the result in the named ``<output_variable>``.
.. signature::
string(JOIN <glue> <output_variable> [<input>...])
.. versionadded:: 3.12
.. versionadded:: 3.12
Join all the ``<input>`` arguments together using the ``<glue>``
string and store the result in the named ``<output_variable>``.
Join all the ``<input>`` arguments together using the ``<glue>``
string and store the result in the named ``<output_variable>``.
To join a list's elements, prefer to use the ``JOIN`` operator
from the :command:`list` command. This allows for the elements to have
special characters like ``;`` in them.
.. _TOLOWER:
.. code-block:: cmake
To join a list's elements, prefer to use the ``JOIN`` operator
from the :command:`list` command. This allows for the elements to have
special characters like ``;`` in them.
.. signature::
string(TOLOWER <string> <output_variable>)
Convert ``<string>`` to lower characters.
.. _TOUPPER:
.. code-block:: cmake
Convert ``<string>`` to lower characters.
.. signature::
string(TOUPPER <string> <output_variable>)
Convert ``<string>`` to upper characters.
.. _LENGTH:
.. code-block:: cmake
Convert ``<string>`` to upper characters.
.. signature::
string(LENGTH <string> <output_variable>)
Store in an ``<output_variable>`` a given string's length in bytes.
Note that this means if ``<string>`` contains multi-byte characters, the
result stored in ``<output_variable>`` will *not* be the number of characters.
.. _SUBSTRING:
.. code-block:: cmake
Store in an ``<output_variable>`` a given string's length in bytes.
Note that this means if ``<string>`` contains multi-byte characters,
the result stored in ``<output_variable>`` will *not* be
the number of characters.
.. signature::
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an ``<output_variable>`` a substring of a given ``<string>``. If
``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
will be returned.
Store in an ``<output_variable>`` a substring of a given ``<string>``. If
``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
will be returned.
.. versionchanged:: 3.2
If ``<string>`` is shorter than ``<length>`` then the end of the string
is used instead. Previous versions of CMake reported an error in this case.
.. versionchanged:: 3.2
If ``<string>`` is shorter than ``<length>``
then the end of the string is used instead.
Previous versions of CMake reported an error in this case.
Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
be exercised if ``<string>`` could contain multi-byte characters.
.. _STRIP:
.. code-block:: cmake
Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
be exercised if ``<string>`` could contain multi-byte characters.
.. signature::
string(STRIP <string> <output_variable>)
Store in an ``<output_variable>`` a substring of a given ``<string>`` with
leading and trailing spaces removed.
.. _GENEX_STRIP:
.. code-block:: cmake
Store in an ``<output_variable>`` a substring of a given ``<string>``
with leading and trailing spaces removed.
.. signature::
string(GENEX_STRIP <string> <output_variable>)
.. versionadded:: 3.1
.. versionadded:: 3.1
Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
from the input ``<string>`` and store the result in the ``<output_variable>``.
.. _REPEAT:
.. code-block:: cmake
Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
from the input ``<string>`` and store the result
in the ``<output_variable>``.
.. signature::
string(REPEAT <string> <count> <output_variable>)
.. versionadded:: 3.15
.. versionadded:: 3.15
Produce the output string as the input ``<string>`` repeated ``<count>`` times.
Produce the output string as the input ``<string>``
repeated ``<count>`` times.
Comparison
^^^^^^^^^^
.. _COMPARE:
.. code-block:: cmake
.. signature::
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
@@ -332,240 +287,217 @@ Comparison
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the ``<output_variable>``.
Compare the strings and store true or false in the ``<output_variable>``.
.. versionadded:: 3.7
Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
.. versionadded:: 3.7
Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
.. _`Supported Hash Algorithms`:
Hashing
^^^^^^^
.. _`HASH`:
.. code-block:: cmake
.. signature::
string(<HASH> <output_variable> <input>)
:target: HASH
Compute a cryptographic hash of the ``<input>`` string.
The supported ``<HASH>`` algorithm names are:
Compute a cryptographic hash of the ``<input>`` string.
The supported ``<HASH>`` algorithm names are:
``MD5``
Message-Digest Algorithm 5, RFC 1321.
``SHA1``
US Secure Hash Algorithm 1, RFC 3174.
``SHA224``
US Secure Hash Algorithms, RFC 4634.
``SHA256``
US Secure Hash Algorithms, RFC 4634.
``SHA384``
US Secure Hash Algorithms, RFC 4634.
``SHA512``
US Secure Hash Algorithms, RFC 4634.
``SHA3_224``
Keccak SHA-3.
``SHA3_256``
Keccak SHA-3.
``SHA3_384``
Keccak SHA-3.
``SHA3_512``
Keccak SHA-3.
``MD5``
Message-Digest Algorithm 5, RFC 1321.
``SHA1``
US Secure Hash Algorithm 1, RFC 3174.
``SHA224``
US Secure Hash Algorithms, RFC 4634.
``SHA256``
US Secure Hash Algorithms, RFC 4634.
``SHA384``
US Secure Hash Algorithms, RFC 4634.
``SHA512``
US Secure Hash Algorithms, RFC 4634.
``SHA3_224``
Keccak SHA-3.
``SHA3_256``
Keccak SHA-3.
``SHA3_384``
Keccak SHA-3.
``SHA3_512``
Keccak SHA-3.
.. versionadded:: 3.8
Added the ``SHA3_*`` hash algorithms.
.. versionadded:: 3.8
Added the ``SHA3_*`` hash algorithms.
Generation
^^^^^^^^^^
.. _ASCII:
.. code-block:: cmake
.. signature::
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
.. _HEX:
.. code-block:: cmake
Convert all numbers into corresponding ASCII characters.
.. signature::
string(HEX <string> <output_variable>)
.. versionadded:: 3.18
.. versionadded:: 3.18
Convert each byte in the input ``<string>`` to its hexadecimal representation
and store the concatenated hex digits in the ``<output_variable>``. Letters in
the output (``a`` through ``f``) are in lowercase.
.. _CONFIGURE:
.. code-block:: cmake
Convert each byte in the input ``<string>`` to its hexadecimal representation
and store the concatenated hex digits in the ``<output_variable>``.
Letters in the output (``a`` through ``f``) are in lowercase.
.. signature::
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOTES])
Transform a ``<string>`` like :command:`configure_file` transforms a file.
.. _MAKE_C_IDENTIFIER:
.. code-block:: cmake
Transform a ``<string>`` like :command:`configure_file` transforms a file.
.. signature::
string(MAKE_C_IDENTIFIER <string> <output_variable>)
Convert each non-alphanumeric character in the input ``<string>`` to an
underscore and store the result in the ``<output_variable>``. If the first
character of the ``<string>`` is a digit, an underscore will also be prepended
to the result.
.. _RANDOM:
.. code-block:: cmake
Convert each non-alphanumeric character in the input ``<string>`` to an
underscore and store the result in the ``<output_variable>``. If the first
character of the ``<string>`` is a digit, an underscore will also be
prepended to the result.
.. signature::
string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
[RANDOM_SEED <seed>] <output_variable>)
Return a random string of given ``<length>`` consisting of
characters from the given ``<alphabet>``. Default length is 5 characters
and default alphabet is all numbers and upper and lower case letters.
If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator.
.. _TIMESTAMP:
.. code-block:: cmake
Return a random string of given ``<length>`` consisting of
characters from the given ``<alphabet>``. Default length is 5 characters
and default alphabet is all numbers and upper and lower case letters.
If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator.
.. signature::
string(TIMESTAMP <output_variable> [<format_string>] [UTC])
Write a string representation of the current date
and/or time to the ``<output_variable>``.
Write a string representation of the current date
and/or time to the ``<output_variable>``.
If the command is unable to obtain a timestamp, the ``<output_variable>``
will be set to the empty string ``""``.
If the command is unable to obtain a timestamp, the ``<output_variable>``
will be set to the empty string ``""``.
The optional ``UTC`` flag requests the current date/time representation to
be in Coordinated Universal Time (UTC) rather than local time.
The optional ``UTC`` flag requests the current date/time representation to
be in Coordinated Universal Time (UTC) rather than local time.
The optional ``<format_string>`` may contain the following format
specifiers:
The optional ``<format_string>`` may contain the following format
specifiers:
``%%``
.. versionadded:: 3.8
A literal percent sign (%).
``%d``
The day of the current month (01-31).
``%H``
The hour on a 24-hour clock (00-23).
``%I``
The hour on a 12-hour clock (01-12).
``%j``
The day of the current year (001-366).
``%m``
The month of the current year (01-12).
``%b``
.. versionadded:: 3.7
Abbreviated month name (e.g. Oct).
``%B``
.. versionadded:: 3.10
Full month name (e.g. October).
``%M``
The minute of the current hour (00-59).
``%s``
.. versionadded:: 3.6
Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
``%S``
The second of the current minute. 60 represents a leap second. (00-60)
``%f``
.. versionadded:: 3.23
The microsecond of the current second (000000-999999).
``%U``
The week number of the current year (00-53).
``%V``
.. versionadded:: 3.22
The ISO 8601 week number of the current year (01-53).
``%w``
The day of the current week. 0 is Sunday. (0-6)
``%a``
.. versionadded:: 3.7
Abbreviated weekday name (e.g. Fri).
``%A``
.. versionadded:: 3.10
Full weekday name (e.g. Friday).
``%y``
The last two digits of the current year (00-99).
``%Y``
The current year.
``%z``
.. versionadded:: 3.26
The offset of the time zone from UTC, in hours and minutes,
with format ``+hhmm`` or ``-hhmm``.
``%Z``
.. versionadded:: 3.26
The time zone name.
Unknown format specifiers will be ignored and copied to the output
as-is.
If no explicit ``<format_string>`` is given, it will default to:
::
%Y-%m-%dT%H:%M:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC.
``%%``
.. versionadded:: 3.8
If the ``SOURCE_DATE_EPOCH`` environment variable is set,
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
A literal percent sign (%).
``%d``
The day of the current month (01-31).
``%H``
The hour on a 24-hour clock (00-23).
``%I``
The hour on a 12-hour clock (01-12).
``%j``
The day of the current year (001-366).
``%m``
The month of the current year (01-12).
``%b``
.. versionadded:: 3.7
Abbreviated month name (e.g. Oct).
``%B``
.. versionadded:: 3.10
Full month name (e.g. October).
``%M``
The minute of the current hour (00-59).
``%s``
.. versionadded:: 3.6
Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
``%S``
The second of the current minute. 60 represents a leap second. (00-60)
``%f``
.. versionadded:: 3.23
The microsecond of the current second (000000-999999).
``%U``
The week number of the current year (00-53).
``%V``
.. versionadded:: 3.22
The ISO 8601 week number of the current year (01-53).
``%w``
The day of the current week. 0 is Sunday. (0-6)
``%a``
.. versionadded:: 3.7
Abbreviated weekday name (e.g. Fri).
``%A``
.. versionadded:: 3.10
Full weekday name (e.g. Friday).
``%y``
The last two digits of the current year (00-99).
``%Y``
The current year.
``%z``
.. versionadded:: 3.26
The offset of the time zone from UTC, in hours and minutes,
with format ``+hhmm`` or ``-hhmm``.
``%Z``
.. versionadded:: 3.26
The time zone name.
Unknown format specifiers will be ignored and copied to the output
as-is.
If no explicit ``<format_string>`` is given, it will default to:
::
%Y-%m-%dT%H:%M:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC.
.. versionadded:: 3.8
If the ``SOURCE_DATE_EPOCH`` environment variable is set,
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
.. _UUID:
.. code-block:: cmake
.. signature::
string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
.. versionadded:: 3.1
.. versionadded:: 3.1
Create a universally unique identifier (aka GUID) as per RFC4122
based on the hash of the combined values of ``<namespace>``
(which itself has to be a valid UUID) and ``<name>``.
The hash algorithm can be either ``MD5`` (Version 3 UUID) or
``SHA1`` (Version 5 UUID).
A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
where each ``x`` represents a lower case hexadecimal character.
Where required, an uppercase representation can be requested
with the optional ``UPPER`` flag.
Create a universally unique identifier (aka GUID) as per RFC4122
based on the hash of the combined values of ``<namespace>``
(which itself has to be a valid UUID) and ``<name>``.
The hash algorithm can be either ``MD5`` (Version 3 UUID) or
``SHA1`` (Version 5 UUID).
A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
where each ``x`` represents a lower case hexadecimal character.
Where required, an uppercase representation can be requested
with the optional ``UPPER`` flag.
.. _JSON:
@@ -586,78 +518,72 @@ Functionality for querying a JSON string.
option is not present, a fatal error message is generated. If no error
occurs, the ``<error-variable>`` will be set to ``NOTFOUND``.
.. _JSON_GET:
.. code-block:: cmake
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
GET <json-string> <member|index> [<member|index> ...])
:target: JSON GET
Get an element from ``<json-string>`` at the location given
by the list of ``<member|index>`` arguments.
Array and object elements will be returned as a JSON string.
Boolean elements will be returned as ``ON`` or ``OFF``.
Null elements will be returned as an empty string.
Number and string types will be returned as strings.
.. _JSON_TYPE:
.. code-block:: cmake
Get an element from ``<json-string>`` at the location given
by the list of ``<member|index>`` arguments.
Array and object elements will be returned as a JSON string.
Boolean elements will be returned as ``ON`` or ``OFF``.
Null elements will be returned as an empty string.
Number and string types will be returned as strings.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
TYPE <json-string> <member|index> [<member|index> ...])
:target: JSON TYPE
Get the type of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The ``<out-var>``
will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
``ARRAY``, or ``OBJECT``.
.. _JSON_MEMBER:
.. code-block:: cmake
Get the type of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The ``<out-var>``
will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
``ARRAY``, or ``OBJECT``.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
MEMBER <json-string>
[<member|index> ...] <index>)
:target: JSON MEMBER
Get the name of the ``<index>``-th member in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of object type.
.. _JSON_LENGTH:
.. code-block:: cmake
Get the name of the ``<index>``-th member in ``<json-string>``
at the location given by the list of ``<member|index>`` arguments.
Requires an element of object type.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
LENGTH <json-string> [<member|index> ...])
:target: JSON LENGTH
Get the length of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of array or object type.
.. _JSON_REMOVE:
.. code-block:: cmake
Get the length of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of array or object type.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
REMOVE <json-string> <member|index> [<member|index> ...])
:target: JSON REMOVE
Remove an element from ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The JSON string
without the removed element will be stored in ``<out-var>``.
.. _JSON_SET:
.. code-block:: cmake
Remove an element from ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The JSON string
without the removed element will be stored in ``<out-var>``.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
SET <json-string> <member|index> [<member|index> ...] <value>)
:target: JSON SET
Set an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments to ``<value>``.
The contents of ``<value>`` should be valid JSON.
.. _JSON_EQUAL:
.. code-block:: cmake
Set an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments to ``<value>``.
The contents of ``<value>`` should be valid JSON.
.. signature::
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
EQUAL <json-string1> <json-string2>)
:target: JSON EQUAL
Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>``
for equality. The contents of ``<json-string1>`` and ``<json-string2>``
should be valid JSON. The ``<out-var>`` will be set to a true value if the
JSON objects are considered equal, or a false value otherwise.
Compare the two JSON objects given by ``<json-string1>``
and ``<json-string2>`` for equality. The contents of ``<json-string1>``
and ``<json-string2>`` should be valid JSON. The ``<out-var>``
will be set to a true value if the JSON objects are considered equal,
or a false value otherwise.
Help/dev/documentation.rst
+149 -35
View File
@@ -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
^^^^^^^^^^^^^^^^^^^^^^^^
Source/cmRST.cxx
+1 -1
View File
@@ -20,7 +20,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot)
: OS(os)
, DocRoot(std::move(docroot))
, CMakeDirective("^.. (cmake:)?("
"command|envvar|genex|variable"
"command|envvar|genex|signature|variable"
")::[ \t]+([^ \t\n]+)$")
, CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$")
, ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$")
Tests/CMakeLib/testRST.expect
+8
View File
@@ -70,6 +70,14 @@ Bracket Comment Content
Generator expression $<OTHER_GENEX> description.
.. cmake:signature:: some_command(SOME_SIGNATURE)
Command some_command SOME_SIGNATURE description.
.. signature:: other_command(OTHER_SIGNATURE)
Command other_command OTHER_SIGNATURE description.
.. cmake:variable:: some_var
Variable some_var description.
Tests/CMakeLib/testRST.rst
+8
View File
@@ -73,6 +73,14 @@ Inline literal ``__`` followed by inline link `Link Text <InternalDest_>`_.
Generator expression $<OTHER_GENEX> description.
.. cmake:signature:: some_command(SOME_SIGNATURE)
Command some_command SOME_SIGNATURE description.
.. signature:: other_command(OTHER_SIGNATURE)
Command other_command OTHER_SIGNATURE description.
.. cmake:variable:: some_var
Variable some_var description.
Utilities/Sphinx/cmake.py
+83 -15
View File
@@ -16,6 +16,9 @@ from pygments.lexers import CMakeLexer
from pygments.token import Name, Operator, Punctuation, String, Text, Comment, Generic, Whitespace, Number
from pygments.lexer import bygroups
# RE to split multiple command signatures
sig_end_re = re.compile(r'(?<=[)])\n')
# Notes on regular expressions below:
# - [\.\+-] are needed for string constants like gtk+-2.0
# - Unix paths are recognized by '/'; support for Windows paths may be added if needed
@@ -57,14 +60,16 @@ CMakeLexer.tokens["root"] = [
# (r'[^<>\])\}\|$"# \t\n]+', Name.Exception), # fallback, for debugging only
]
from docutils.utils.code_analyzer import Lexer, LexerError
from docutils.parsers.rst import Directive, directives
from docutils.transforms import Transform
from docutils import io, nodes
from sphinx.directives import ObjectDescription
from sphinx.directives import ObjectDescription, nl_escape_re
from sphinx.domains import Domain, ObjType
from sphinx.roles import XRefRole
from sphinx.util.nodes import make_refnode
from sphinx.util import ws_re
from sphinx import addnodes
sphinx_before_1_4 = False
@@ -286,9 +291,9 @@ class CMakeObject(ObjectDescription):
def add_target_and_index(self, name, sig, signode):
if self.objtype == 'command':
targetname = name.lower()
targetname = name.lower()
else:
targetname = name
targetname = name
targetid = '%s:%s' % (self.objtype, targetname)
if targetid not in self.state.document.ids:
signode['names'].append(targetid)
@@ -302,6 +307,79 @@ class CMakeObject(ObjectDescription):
if make_index_entry:
self.indexnode['entries'].append(make_index_entry(name, targetid))
class CMakeSignatureObject(CMakeObject):
object_type = 'signature'
option_spec = {
'target': directives.unchanged,
}
def get_signatures(self):
content = nl_escape_re.sub('', self.arguments[0])
lines = sig_end_re.split(content)
return [ws_re.sub(' ', line.strip()) for line in lines]
def handle_signature(self, sig, signode):
language = 'cmake'
classes = ['code', 'cmake', 'highlight']
node = addnodes.desc_name(sig, '', classes=classes)
try:
tokens = Lexer(sig, language, 'short')
except LexerError as error:
if self.state.document.settings.report_level > 2:
# Silently insert without syntax highlighting.
tokens = Lexer(sig, language, 'none')
else:
raise self.warning(error)
for classes, value in tokens:
if classes:
node += nodes.inline(value, value, classes=classes)
else:
node += nodes.Text(value)
signode.clear()
signode += node
return sig
def __init__(self, *args, **kwargs):
self.targetnames = {}
super().__init__(*args, **kwargs)
def add_target_and_index(self, name, sig, signode):
if name in self.targetnames:
targetname = self.targetnames[name].lower()
else:
def extract_keywords(params):
for p in params:
if p[0].isalpha():
yield p
else:
return
keywords = extract_keywords(name.split('(')[1].split())
targetname = ' '.join(keywords).lower()
targetid = nodes.make_id(targetname)
if targetid not in self.state.document.ids:
signode['names'].append(targetname)
signode['ids'].append(targetid)
signode['first'] = (not self.names)
self.state.document.note_explicit_target(signode)
def run(self):
targets = self.options.get('target')
if targets is not None:
signatures = self.get_signatures()
targets = [t.strip() for t in targets.split('\n')]
for signature, target in zip(signatures, targets):
self.targetnames[signature] = target
return super().run()
class CMakeXRefRole(XRefRole):
# See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
@@ -411,19 +489,9 @@ class CMakeDomain(Domain):
'command': CMakeObject,
'envvar': CMakeObject,
'genex': CMakeObject,
'signature': CMakeSignatureObject,
'variable': CMakeObject,
# Other object types cannot be created except by the CMakeTransform
# 'generator': CMakeObject,
# 'module': CMakeObject,
# 'policy': CMakeObject,
# 'prop_cache': CMakeObject,
# 'prop_dir': CMakeObject,
# 'prop_gbl': CMakeObject,
# 'prop_inst': CMakeObject,
# 'prop_sf': CMakeObject,
# 'prop_test': CMakeObject,
# 'prop_tgt': CMakeObject,
# 'manual': CMakeObject,
# Other `object_types` cannot be created except by the `CMakeTransform`
}
roles = {
'command': CMakeXRefRole(fix_parens = True, lowercase = True),
Utilities/Sphinx/static/cmake.css
+23
View File
@@ -17,6 +17,29 @@ div.sphinxsidebarwrapper {
background-color: #dfdfdf;
}
/* Apply <pre> style (from classic.css) to signature directive argument. */
.signature .sig {
padding: 5px;
background-color: #eeeeee;
color: #333333;
line-height: 120%;
border: 1px solid #ac9;
border-left: none;
border-right: none;
}
/* Add additional styling to signature directive argument. */
.signature .sig {
margin-bottom: 5px;
padding-left: calc(5px + 3em);
text-indent: -3em;
font-family: monospace;
}
.signature .sig .code.sig-name {
font-weight: normal;
}
/* Remove unwanted margin in case list item contains a div-wrapping
directive like `.. versionadded` or `.. deprecated`. */
dd > :first-child > p {