You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
369 lines
16 KiB
369 lines
16 KiB
"""
|
|
sphinx.util.docfields
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
"Doc fields" are reST field lists in object descriptions that will
|
|
be domain-specifically transformed to a more appealing presentation.
|
|
|
|
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
|
|
:license: BSD, see LICENSE for details.
|
|
"""
|
|
|
|
import warnings
|
|
from typing import Any, Dict, List, Tuple, Union, cast
|
|
|
|
from docutils import nodes
|
|
from docutils.nodes import Node
|
|
|
|
from sphinx import addnodes
|
|
from sphinx.deprecation import RemovedInSphinx40Warning
|
|
from sphinx.util.typing import TextlikeNode
|
|
|
|
if False:
|
|
# For type annotation
|
|
from typing import Type # for python3.5.1
|
|
|
|
from sphinx.directive import ObjectDescription
|
|
from sphinx.environment import BuildEnvironment
|
|
|
|
|
|
def _is_single_paragraph(node: nodes.field_body) -> bool:
|
|
"""True if the node only contains one paragraph (and system messages)."""
|
|
if len(node) == 0:
|
|
return False
|
|
elif len(node) > 1:
|
|
for subnode in node[1:]: # type: nodes.Node
|
|
if not isinstance(subnode, nodes.system_message):
|
|
return False
|
|
if isinstance(node[0], nodes.paragraph):
|
|
return True
|
|
return False
|
|
|
|
|
|
class Field:
|
|
"""A doc field that is never grouped. It can have an argument or not, the
|
|
argument can be linked using a specified *rolename*. Field should be used
|
|
for doc fields that usually don't occur more than once.
|
|
|
|
The body can be linked using a specified *bodyrolename* if the content is
|
|
just a single inline or text node.
|
|
|
|
Example::
|
|
|
|
:returns: description of the return value
|
|
:rtype: description of the return type
|
|
"""
|
|
is_grouped = False
|
|
is_typed = False
|
|
|
|
def __init__(self, name: str, names: Tuple[str, ...] = (), label: str = None,
|
|
has_arg: bool = True, rolename: str = None, bodyrolename: str = None) -> None:
|
|
self.name = name
|
|
self.names = names
|
|
self.label = label
|
|
self.has_arg = has_arg
|
|
self.rolename = rolename
|
|
self.bodyrolename = bodyrolename
|
|
|
|
def make_xref(self, rolename: str, domain: str, target: str,
|
|
innernode: "Type[TextlikeNode]" = addnodes.literal_emphasis,
|
|
contnode: Node = None, env: "BuildEnvironment" = None) -> Node:
|
|
if not rolename:
|
|
return contnode or innernode(target, target)
|
|
refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
|
|
reftype=rolename, reftarget=target)
|
|
refnode += contnode or innernode(target, target)
|
|
if env:
|
|
env.get_domain(domain).process_field_xref(refnode)
|
|
return refnode
|
|
|
|
def make_xrefs(self, rolename: str, domain: str, target: str,
|
|
innernode: "Type[TextlikeNode]" = addnodes.literal_emphasis,
|
|
contnode: Node = None, env: "BuildEnvironment" = None) -> List[Node]:
|
|
return [self.make_xref(rolename, domain, target, innernode, contnode, env)]
|
|
|
|
def make_entry(self, fieldarg: str, content: List[Node]) -> Tuple[str, List[Node]]:
|
|
return (fieldarg, content)
|
|
|
|
def make_field(self, types: Dict[str, List[Node]], domain: str,
|
|
item: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
|
|
fieldarg, content = item
|
|
fieldname = nodes.field_name('', self.label)
|
|
if fieldarg:
|
|
fieldname += nodes.Text(' ')
|
|
fieldname.extend(self.make_xrefs(self.rolename, domain,
|
|
fieldarg, nodes.Text, env=env))
|
|
|
|
if len(content) == 1 and (
|
|
isinstance(content[0], nodes.Text) or
|
|
(isinstance(content[0], nodes.inline) and len(content[0]) == 1 and
|
|
isinstance(content[0][0], nodes.Text))):
|
|
content = self.make_xrefs(self.bodyrolename, domain,
|
|
content[0].astext(), contnode=content[0], env=env)
|
|
fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
|
|
class GroupedField(Field):
|
|
"""
|
|
A doc field that is grouped; i.e., all fields of that type will be
|
|
transformed into one field with its body being a bulleted list. It always
|
|
has an argument. The argument can be linked using the given *rolename*.
|
|
GroupedField should be used for doc fields that can occur more than once.
|
|
If *can_collapse* is true, this field will revert to a Field if only used
|
|
once.
|
|
|
|
Example::
|
|
|
|
:raises ErrorClass: description when it is raised
|
|
"""
|
|
is_grouped = True
|
|
list_type = nodes.bullet_list
|
|
|
|
def __init__(self, name: str, names: Tuple[str, ...] = (), label: str = None,
|
|
rolename: str = None, can_collapse: bool = False) -> None:
|
|
super().__init__(name, names, label, True, rolename)
|
|
self.can_collapse = can_collapse
|
|
|
|
def make_field(self, types: Dict[str, List[Node]], domain: str,
|
|
items: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
|
|
fieldname = nodes.field_name('', self.label)
|
|
listnode = self.list_type()
|
|
for fieldarg, content in items:
|
|
par = nodes.paragraph()
|
|
par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
|
|
addnodes.literal_strong, env=env))
|
|
par += nodes.Text(' -- ')
|
|
par += content
|
|
listnode += nodes.list_item('', par)
|
|
|
|
if len(items) == 1 and self.can_collapse:
|
|
list_item = cast(nodes.list_item, listnode[0])
|
|
fieldbody = nodes.field_body('', list_item[0])
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
fieldbody = nodes.field_body('', listnode)
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
|
|
class TypedField(GroupedField):
|
|
"""
|
|
A doc field that is grouped and has type information for the arguments. It
|
|
always has an argument. The argument can be linked using the given
|
|
*rolename*, the type using the given *typerolename*.
|
|
|
|
Two uses are possible: either parameter and type description are given
|
|
separately, using a field from *names* and one from *typenames*,
|
|
respectively, or both are given using a field from *names*, see the example.
|
|
|
|
Example::
|
|
|
|
:param foo: description of parameter foo
|
|
:type foo: SomeClass
|
|
|
|
-- or --
|
|
|
|
:param SomeClass foo: description of parameter foo
|
|
"""
|
|
is_typed = True
|
|
|
|
def __init__(self, name: str, names: Tuple[str, ...] = (), typenames: Tuple[str, ...] = (),
|
|
label: str = None, rolename: str = None, typerolename: str = None,
|
|
can_collapse: bool = False) -> None:
|
|
super().__init__(name, names, label, rolename, can_collapse)
|
|
self.typenames = typenames
|
|
self.typerolename = typerolename
|
|
|
|
def make_field(self, types: Dict[str, List[Node]], domain: str,
|
|
items: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
|
|
def handle_item(fieldarg: str, content: str) -> nodes.paragraph:
|
|
par = nodes.paragraph()
|
|
par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
|
|
addnodes.literal_strong, env=env))
|
|
if fieldarg in types:
|
|
par += nodes.Text(' (')
|
|
# NOTE: using .pop() here to prevent a single type node to be
|
|
# inserted twice into the doctree, which leads to
|
|
# inconsistencies later when references are resolved
|
|
fieldtype = types.pop(fieldarg)
|
|
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
|
|
typename = fieldtype[0].astext()
|
|
par.extend(self.make_xrefs(self.typerolename, domain, typename,
|
|
addnodes.literal_emphasis, env=env))
|
|
else:
|
|
par += fieldtype
|
|
par += nodes.Text(')')
|
|
par += nodes.Text(' -- ')
|
|
par += content
|
|
return par
|
|
|
|
fieldname = nodes.field_name('', self.label)
|
|
if len(items) == 1 and self.can_collapse:
|
|
fieldarg, content = items[0]
|
|
bodynode = handle_item(fieldarg, content) # type: nodes.Node
|
|
else:
|
|
bodynode = self.list_type()
|
|
for fieldarg, content in items:
|
|
bodynode += nodes.list_item('', handle_item(fieldarg, content))
|
|
fieldbody = nodes.field_body('', bodynode)
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
|
|
class DocFieldTransformer:
|
|
"""
|
|
Transforms field lists in "doc field" syntax into better-looking
|
|
equivalents, using the field type definitions given on a domain.
|
|
"""
|
|
typemap = None # type: Dict[str, Tuple[Field, bool]]
|
|
|
|
def __init__(self, directive: "ObjectDescription") -> None:
|
|
self.directive = directive
|
|
|
|
try:
|
|
self.typemap = directive.get_field_type_map()
|
|
except Exception:
|
|
# for 3rd party extensions directly calls this transformer.
|
|
warnings.warn('DocFieldTransformer expects given directive object is a subclass '
|
|
'of ObjectDescription.', RemovedInSphinx40Warning, stacklevel=2)
|
|
self.typemap = self.preprocess_fieldtypes(directive.__class__.doc_field_types)
|
|
|
|
def preprocess_fieldtypes(self, types: List[Field]) -> Dict[str, Tuple[Field, bool]]:
|
|
warnings.warn('DocFieldTransformer.preprocess_fieldtypes() is deprecated.',
|
|
RemovedInSphinx40Warning, stacklevel=2)
|
|
typemap = {}
|
|
for fieldtype in types:
|
|
for name in fieldtype.names:
|
|
typemap[name] = fieldtype, False
|
|
if fieldtype.is_typed:
|
|
typed_field = cast(TypedField, fieldtype)
|
|
for name in typed_field.typenames:
|
|
typemap[name] = typed_field, True
|
|
return typemap
|
|
|
|
def transform_all(self, node: addnodes.desc_content) -> None:
|
|
"""Transform all field list children of a node."""
|
|
# don't traverse, only handle field lists that are immediate children
|
|
for child in node:
|
|
if isinstance(child, nodes.field_list):
|
|
self.transform(child)
|
|
|
|
def transform(self, node: nodes.field_list) -> None:
|
|
"""Transform a single field list *node*."""
|
|
typemap = self.typemap
|
|
|
|
entries = [] # type: List[Union[nodes.field, Tuple[Field, Any]]]
|
|
groupindices = {} # type: Dict[str, int]
|
|
types = {} # type: Dict[str, Dict]
|
|
|
|
# step 1: traverse all fields and collect field types and content
|
|
for field in cast(List[nodes.field], node):
|
|
assert len(field) == 2
|
|
field_name = cast(nodes.field_name, field[0])
|
|
field_body = cast(nodes.field_body, field[1])
|
|
try:
|
|
# split into field type and argument
|
|
fieldtype_name, fieldarg = field_name.astext().split(None, 1)
|
|
except ValueError:
|
|
# maybe an argument-less field type?
|
|
fieldtype_name, fieldarg = field_name.astext(), ''
|
|
typedesc, is_typefield = typemap.get(fieldtype_name, (None, None))
|
|
|
|
# collect the content, trying not to keep unnecessary paragraphs
|
|
if _is_single_paragraph(field_body):
|
|
paragraph = cast(nodes.paragraph, field_body[0])
|
|
content = paragraph.children
|
|
else:
|
|
content = field_body.children
|
|
|
|
# sort out unknown fields
|
|
if typedesc is None or typedesc.has_arg != bool(fieldarg):
|
|
# either the field name is unknown, or the argument doesn't
|
|
# match the spec; capitalize field name and be done with it
|
|
new_fieldname = fieldtype_name[0:1].upper() + fieldtype_name[1:]
|
|
if fieldarg:
|
|
new_fieldname += ' ' + fieldarg
|
|
field_name[0] = nodes.Text(new_fieldname)
|
|
entries.append(field)
|
|
|
|
# but if this has a type then we can at least link it
|
|
if (typedesc and is_typefield and content and
|
|
len(content) == 1 and isinstance(content[0], nodes.Text)):
|
|
typed_field = cast(TypedField, typedesc)
|
|
target = content[0].astext()
|
|
xrefs = typed_field.make_xrefs(
|
|
typed_field.typerolename,
|
|
self.directive.domain,
|
|
target,
|
|
contnode=content[0],
|
|
env=self.directive.state.document.settings.env
|
|
)
|
|
if _is_single_paragraph(field_body):
|
|
paragraph = cast(nodes.paragraph, field_body[0])
|
|
paragraph.clear()
|
|
paragraph.extend(xrefs)
|
|
else:
|
|
field_body.clear()
|
|
field_body += nodes.paragraph('', '', *xrefs)
|
|
|
|
continue
|
|
|
|
typename = typedesc.name
|
|
|
|
# if the field specifies a type, put it in the types collection
|
|
if is_typefield:
|
|
# filter out only inline nodes; others will result in invalid
|
|
# markup being written out
|
|
content = [n for n in content if isinstance(n, nodes.Inline) or
|
|
isinstance(n, nodes.Text)]
|
|
if content:
|
|
types.setdefault(typename, {})[fieldarg] = content
|
|
continue
|
|
|
|
# also support syntax like ``:param type name:``
|
|
if typedesc.is_typed:
|
|
try:
|
|
argtype, argname = fieldarg.split(None, 1)
|
|
except ValueError:
|
|
pass
|
|
else:
|
|
types.setdefault(typename, {})[argname] = \
|
|
[nodes.Text(argtype)]
|
|
fieldarg = argname
|
|
|
|
translatable_content = nodes.inline(field_body.rawsource,
|
|
translatable=True)
|
|
translatable_content.document = field_body.parent.document
|
|
translatable_content.source = field_body.parent.source
|
|
translatable_content.line = field_body.parent.line
|
|
translatable_content += content
|
|
|
|
# grouped entries need to be collected in one entry, while others
|
|
# get one entry per field
|
|
if typedesc.is_grouped:
|
|
if typename in groupindices:
|
|
group = cast(Tuple[Field, List], entries[groupindices[typename]])
|
|
else:
|
|
groupindices[typename] = len(entries)
|
|
group = (typedesc, [])
|
|
entries.append(group)
|
|
new_entry = typedesc.make_entry(fieldarg, [translatable_content])
|
|
group[1].append(new_entry)
|
|
else:
|
|
new_entry = typedesc.make_entry(fieldarg, [translatable_content])
|
|
entries.append((typedesc, new_entry))
|
|
|
|
# step 2: all entries are collected, construct the new field list
|
|
new_list = nodes.field_list()
|
|
for entry in entries:
|
|
if isinstance(entry, nodes.field):
|
|
# pass-through old field
|
|
new_list += entry
|
|
else:
|
|
fieldtype, items = entry
|
|
fieldtypes = types.get(fieldtype.name, {})
|
|
env = self.directive.state.document.settings.env
|
|
new_list += fieldtype.make_field(fieldtypes, self.directive.domain,
|
|
items, env=env)
|
|
|
|
node.replace_self(new_list)
|