def visit_field(self, node: Node) -> None:
# Remove the field from the tree.
node.parent.remove(node)
# Extract the field name & optional argument
tag = node[0].astext().split(None, 1)
tagname = tag[0]
if len(tag)>1: arg = tag[1]
else: arg = None
# Handle special fields:
fbody = node[1]
if arg is None:
for (list_tag, entry_tag) in CONSOLIDATED_FIELDS.items():
if tagname.lower() == list_tag:
try:
self.handle_consolidated_field(fbody, entry_tag)
return
except ValueError as e:
estr = 'Unable to split consolidated field '
estr += f'"{tagname}" - {e}'
self._errors.append(ParseError(estr, node.line,
is_fatal=False))
# Use a @newfield to let it be displayed as-is.
if tagname.lower() not in self._newfields:
newfield = Field('newfield', tagname.lower(),
ParsedPlaintextDocstring(tagname),
node.line - 1)
self.fields.append(newfield)
self._newfields.add(tagname.lower())
self._add_field(tagname, arg, fbody, node.line)
def report(self, error: docutils.nodes.system_message) -> None:
level: int = error['level']
is_fatal = level >= Reporter.ERROR_LEVEL
linenum: Optional[int] = error.get('line')
msg = ''.join(c.astext() for c in error)
self._errors.append(ParseError(msg, linenum, is_fatal))
def report(self, error):
try: is_fatal = int(error['level']) > 2
except: is_fatal = True
try: linenum = int(error['line'])
except: linenum = None
msg = ''.join([c.astext().encode(self._encoding, self._error_handler)
for c in error])
self._errors.append(ParseError(msg, linenum, is_fatal))
def format_docstring(obj: model.Documentable) -> Tag:
"""Generate an HTML representation of a docstring"""
doc, source = get_docstring(obj)
# Use cached or split version if possible.
pdoc = obj.parsed_docstring
if source is None:
if pdoc is None:
# We don't use 'source' if pdoc is None, but mypy is not that
# sophisticated, so we fool it by assigning a dummy object.
source = obj
else:
# A split field is documented by its parent.
source = obj.parent
assert source is not None
if pdoc is None and doc is not None:
pdoc = parse_docstring(obj, doc, source)
obj.parsed_docstring = pdoc
ret: Tag = tags.div
if pdoc is None:
ret(tags.p(class_='undocumented')("Undocumented"))
else:
try:
stan = pdoc.to_stan(_EpydocLinker(source))
except Exception as e:
errs = [ParseError(f'{e.__class__.__name__}: {e}', 1)]
if doc is None:
stan = tags.p(class_="undocumented")('Broken description')
else:
pdoc_plain = pydoctor.epydoc.markup.plaintext.parse_docstring(
doc, errs)
stan = pdoc_plain.to_stan(_EpydocLinker(source))
reportErrors(source, errs)
if stan.tagName:
ret(stan)
else:
ret(*stan.children)
fh = FieldHandler(obj)
if isinstance(obj, model.Function):
fh.set_param_types_from_annotations(obj.annotations)
if pdoc is not None:
for field in pdoc.fields:
fh.handle(Field.from_epydoc(field, source))
if isinstance(obj, model.Function):
fh.resolve_types()
ret(fh.format())
return ret
def report(self, error):
try:
is_fatal = int(error['level']) > 2
except:
is_fatal = True
try:
linenum = int(error['line'])
except:
linenum = None
msg = ''.join(c.astext() for c in error)
self._errors.append(ParseError(msg, linenum, is_fatal))
def parse_docstring(
obj: model.Documentable,
doc: str,
source: model.Documentable,
) -> ParsedDocstring:
"""Parse a docstring.
@param obj: The object we're parsing the documentation for.
@param doc: The docstring.
@param source: The object on which the docstring is defined.
This can differ from C{obj} if the docstring is inherited.
"""
parser = get_parser(obj)
errs: List[ParseError] = []
try:
pdoc = parser(doc, errs)
except Exception as e:
errs.append(ParseError(f'{e.__class__.__name__}: {e}', 1))
pdoc = pydoctor.epydoc.markup.plaintext.parse_docstring(doc, errs)
if errs:
reportErrors(source, errs)
return pdoc