def extract_fields(obj: model.Documentable) -> None:
"""Populate Attributes for module/class variables using fields from
that module/class's docstring.
Must only be called for objects that have a docstring.
"""
doc = obj.docstring
assert doc is not None, obj
pdoc = parse_docstring(obj, doc, obj)
obj.parsed_docstring = pdoc
for field in pdoc.fields:
tag = field.tag()
if tag in ['ivar', 'cvar', 'var', 'type']:
arg = field.arg()
if arg is None:
obj.report("Missing field name in @%s" % (tag, ), 'docstring',
field.lineno)
continue
attrobj: Optional[model.Documentable] = obj.contents.get(arg)
if attrobj is None:
attrobj = obj.system.Attribute(obj.system, arg, obj)
attrobj.kind = None
attrobj.parentMod = obj.parentMod
obj.system.addObject(attrobj)
attrobj.setLineNumber(obj.docstring_lineno + field.lineno)
if tag == 'type':
attrobj.parsed_type = field.body()
else:
attrobj.parsed_docstring = field.body()
attrobj.kind = field_name_to_human_name[tag]
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