Help: Introduce `signature` and `synopsis` directives to Sphinx
I've ported the cmake_policy()
command to use the added directives and roles just to play w/ 'em (one page per commit for easy review).
The .. signature::
directive aimed to define a command signature variant. It may have the following options:
-
:kw:
comma or|
separate list of the named arguments to turn into hyperlinks in the generated synopsis. -
:synopsis:
an alternative text to use in a synopsis block. Sometimes the full signature is too long. The option also has two special values:-
skip
to omit the signature from Synopsis -
same as above
to omit the signature from Synopsis but turn the specified named arguments (:kw:
option) into links in the previously added signature (e.g.,string(JSON...)
command use it).
-
Content of the .. signature::
consists of two blocks split by empty line:
- CMake pseudo-code highlighted block.
- An RST description of the signature.
Example:
.. signature::
:kw: FIND
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.
Note, the description need not be indented relative to the CMake code block. It'll be done automatically.
The .. synopsis::
directive, if no content provided, used to generate the parsed-literal-like but highlighted block out of the .. signature::
directives found on the current page, grouped by the section names they were found. If any content has been given (e.g., for commands w/ the only signature, like block
), it'll be highlighted as CMake (pseudo-code) and no further .. signature::
directives considered.
To refer to the added signature one may use :signature:
role. Example:
To refer to a signature one can use :signature:`cmd(kw)` role or :signature`custom text <cmd:kw>`.
Where `cmd` is a command name and `kw` is a `kw` option given to the `.. signature::` directive.
Also, fixed the syntax to inhibit reference for :command:
role w/ custom text:
This is a "standard" syntax to inhibit reference: :command:`!cmake_policy`.
However, roles w/ custom text (e.g., like :command:`!cmake_policy(POP)`) were broken.
Motivated by discussion in !7873 (comment 1273219).
Topic-rename: sphinx-signature