Skip to content

Help: Introduce `signature` and `synopsis` directives to Sphinx

Alex Turbov requested to merge zaufi/cmake:feature/sphinx-signature into master

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.

Rendered examples

Screenshot_20230123_073058 Screenshot_20230123_073535 Screenshot_20230123_073715 Screenshot_20230123_073824 Screenshot_20230123_074442

Motivated by discussion in !7873 (comment 1273219).

Topic-rename: sphinx-signature

Edited by Alex Turbov

Merge request reports