diff options
Diffstat (limited to 'Help/dev/documentation.rst')
| -rw-r--r-- | Help/dev/documentation.rst | 17 |
1 files changed, 17 insertions, 0 deletions
diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 1dd23c6..b7a77c9 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -305,6 +305,23 @@ The ``signature`` directive generates a hyperlink target for each signature: 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. |