Utilities/Sphinx: Improve word wrap of signatures
Implement logic to support several styles of parsing in the new signature directive that control where line breaks are allowed in a signature. The default is 'smart', which forbids breaks inside of square- or angle-brackets. The 'verbatim' option forbids all breaks. In all cases, breaks are always allowed where a newline appears in the source. This seems to Just Work for most writers, but HTML needs some special handling that is accomplished by a new CSS rule and assigning the 'nbsp' class to spaces that are not allowed to break. (ROFF's line wrapping is rather unfortunate here, as it prefers splitting and hyphenating words rather than breaking at a space.)
This commit is contained in:
Matthew Woehlke
parent
9db40bec4e
commit
39ecaa5da1
@ -301,6 +301,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.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ import os
|
||||
import re
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any, cast
|
||||
from typing import Any, List, cast
|
||||
|
||||
# Override much of pygments' CMakeLexer.
|
||||
# We need to parse CMake syntax definitions, not CMake code.
|
||||
@ -319,14 +319,69 @@ class CMakeObject(ObjectDescription):
|
||||
class CMakeSignatureObject(CMakeObject):
|
||||
object_type = 'signature'
|
||||
|
||||
BREAK_ALL = 'all'
|
||||
BREAK_SMART = 'smart'
|
||||
BREAK_VERBATIM = 'verbatim'
|
||||
|
||||
BREAK_CHOICES = {BREAK_ALL, BREAK_SMART, BREAK_VERBATIM}
|
||||
|
||||
def break_option(argument):
|
||||
return directives.choice(argument, CMakeSignatureObject.BREAK_CHOICES)
|
||||
|
||||
option_spec = {
|
||||
'target': directives.unchanged,
|
||||
'break': break_option,
|
||||
}
|
||||
|
||||
def get_signatures(self):
|
||||
def _break_signature_all(sig: str) -> str:
|
||||
return ws_re.sub(' ', sig)
|
||||
|
||||
def _break_signature_verbatim(sig: str) -> str:
|
||||
lines = [ws_re.sub('\xa0', line.strip()) for line in sig.split('\n')]
|
||||
return ' '.join(lines)
|
||||
|
||||
def _break_signature_smart(sig: str) -> str:
|
||||
tokens = []
|
||||
for line in sig.split('\n'):
|
||||
token = ''
|
||||
delim = ''
|
||||
|
||||
for c in line.strip():
|
||||
if len(delim) == 0 and ws_re.match(c):
|
||||
if len(token):
|
||||
tokens.append(ws_re.sub('\xa0', token))
|
||||
token = ''
|
||||
else:
|
||||
if c == '[':
|
||||
delim += ']'
|
||||
elif c == '<':
|
||||
delim += '>'
|
||||
elif len(delim) and c == delim[-1]:
|
||||
delim = delim[:-1]
|
||||
token += c
|
||||
|
||||
if len(token):
|
||||
tokens.append(ws_re.sub('\xa0', token))
|
||||
|
||||
return ' '.join(tokens)
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
self.targetnames = {}
|
||||
self.break_style = CMakeSignatureObject.BREAK_SMART
|
||||
super().__init__(*args, **kwargs)
|
||||
|
||||
def get_signatures(self) -> List[str]:
|
||||
content = nl_escape_re.sub('', self.arguments[0])
|
||||
lines = sig_end_re.split(content)
|
||||
return [ws_re.sub(' ', line.strip()) for line in lines]
|
||||
|
||||
if self.break_style == CMakeSignatureObject.BREAK_VERBATIM:
|
||||
fixup = CMakeSignatureObject._break_signature_verbatim
|
||||
elif self.break_style == CMakeSignatureObject.BREAK_SMART:
|
||||
fixup = CMakeSignatureObject._break_signature_smart
|
||||
else:
|
||||
fixup = CMakeSignatureObject._break_signature_all
|
||||
|
||||
return [fixup(line.strip()) for line in lines]
|
||||
|
||||
def handle_signature(self, sig, signode):
|
||||
language = 'cmake'
|
||||
@ -344,7 +399,9 @@ class CMakeSignatureObject(CMakeObject):
|
||||
raise self.warning(error)
|
||||
|
||||
for classes, value in tokens:
|
||||
if classes:
|
||||
if value == '\xa0':
|
||||
node += nodes.inline(value, value, classes=['nbsp'])
|
||||
elif classes:
|
||||
node += nodes.inline(value, value, classes=classes)
|
||||
else:
|
||||
node += nodes.Text(value)
|
||||
@ -354,13 +411,10 @@ class CMakeSignatureObject(CMakeObject):
|
||||
|
||||
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:
|
||||
sigargs = self.targetnames[name]
|
||||
sig = sig.replace('\xa0', ' ')
|
||||
if sig in self.targetnames:
|
||||
sigargs = self.targetnames[sig]
|
||||
else:
|
||||
def extract_keywords(params):
|
||||
for p in params:
|
||||
@ -369,7 +423,7 @@ class CMakeSignatureObject(CMakeObject):
|
||||
else:
|
||||
return
|
||||
|
||||
keywords = extract_keywords(name.split('(')[1].split())
|
||||
keywords = extract_keywords(sig.split('(')[1].split())
|
||||
sigargs = ' '.join(keywords)
|
||||
targetname = sigargs.lower()
|
||||
targetid = nodes.make_id(targetname)
|
||||
@ -381,7 +435,7 @@ class CMakeSignatureObject(CMakeObject):
|
||||
self.state.document.note_explicit_target(signode)
|
||||
|
||||
# Register the signature as a command object.
|
||||
command = name.split('(')[0].lower()
|
||||
command = sig.split('(')[0].lower()
|
||||
refname = f'{command}({sigargs})'
|
||||
refid = f'command:{command}({targetname})'
|
||||
|
||||
@ -390,6 +444,8 @@ class CMakeSignatureObject(CMakeObject):
|
||||
node_id=targetid, location=signode)
|
||||
|
||||
def run(self):
|
||||
self.break_style = CMakeSignatureObject.BREAK_ALL
|
||||
|
||||
targets = self.options.get('target')
|
||||
if targets is not None:
|
||||
signatures = self.get_signatures()
|
||||
@ -397,6 +453,9 @@ class CMakeSignatureObject(CMakeObject):
|
||||
for signature, target in zip(signatures, targets):
|
||||
self.targetnames[signature] = target
|
||||
|
||||
self.break_style = (
|
||||
self.options.get('break', CMakeSignatureObject.BREAK_SMART))
|
||||
|
||||
return super().run()
|
||||
|
||||
class CMakeXRefRole(XRefRole):
|
||||
|
||||
@ -40,6 +40,11 @@ div.sphinxsidebarwrapper {
|
||||
font-weight: normal;
|
||||
}
|
||||
|
||||
/* Implement non-breaking spaces in signatures. */
|
||||
.nbsp {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
/* Remove unwanted margin in case list item contains a div-wrapping
|
||||
directive like `.. versionadded` or `.. deprecated`. */
|
||||
dd > :first-child > p {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user