def _get_title(self, obj: docspec.ApiObject) -> str:
title = obj.name
if (self.add_method_class_prefix and self._is_method(obj)) or \
(self.add_member_class_prefix and isinstance(obj, docspec.Data)):
title = self._get_parent(obj).name + '.' + title
elif self.add_full_prefix and not self._is_method(obj):
title = obj.path()
if isinstance(obj, docspec.Function):
if self.signature_in_header:
title += '(' + self._format_arglist(obj) + ')'
if self.code_headers:
if self.html_headers or self.sub_prefix:
if self.sub_prefix and '.' in title:
prefix, title = title.rpartition('.')[::2]
title = '<sub>{}.</sub>{}'.format(prefix, title)
title = '<code>{}</code>'.format(title)
else:
title = '`{}`'.format(title)
else:
title = self._escape(title)
if isinstance(obj, docspec.Module) and self.descriptive_module_title:
title = 'Module ' + title
if isinstance(obj, docspec.Class) and self.descriptive_class_title:
title += ' Objects'
return title
def _process(self, node: docspec.ApiObject):
if not node.docstring:
return
lines = []
current_lines = []
in_codeblock = False
keyword = None
def _commit():
if keyword:
generate_sections_markdown(lines, {keyword: current_lines})
else:
lines.extend(current_lines)
current_lines.clear()
for line in node.docstring.split('\n'):
if line.startswith("```"):
in_codeblock = not in_codeblock
current_lines.append(line)
continue
if in_codeblock:
current_lines.append(line)
continue
line = line.strip()
if line in self._keywords_map:
_commit()
keyword = self._keywords_map[line]
continue
if keyword is None:
lines.append(line)
continue
for param_re in self._param_res:
param_match = param_re.match(line)
if param_match:
if 'type' in param_match.groupdict():
current_lines.append(
'- `{param}` _{type}_ - {desc}'.format(
**param_match.groupdict()))
else:
current_lines.append('- `{param}` - {desc}'.format(
**param_match.groupdict()))
break
if not param_match:
current_lines.append(' {line}'.format(line=line))
_commit()
node.docstring = '\n'.join(lines)
def _process(self, node: docspec.ApiObject):
if not getattr(node, 'docstring', None):
return
lines = []
codeblock_opened = False
current_section = None
for line in node.docstring.split('\n'):
if line.startswith("```"):
codeblock_opened = (not codeblock_opened)
if not codeblock_opened:
line, current_section = self._preprocess_line(
line, current_section)
lines.append(line)
node.docstring = '\n'.join(lines)
def _process(self, obj: docspec.ApiObject):
if not obj.docstring:
return None
for name in ('google', 'pydocmd', 'sphinx'):
indicator = '@doc:fmt:' + name
if indicator in obj.docstring:
obj.docstring = obj.docstring.replace(indicator, '')
return getattr(self, name)._process(obj)
if self.sphinx.check_docstring_format(obj.docstring):
return self.sphinx._process(obj)
if self.google.check_docstring_format(obj.docstring):
return self.google._process(obj)
return self.pydocmd._process(obj)
def _preprocess_refs(
self,
node: docspec.ApiObject,
resolver: Resolver,
reverse: docspec.ReverseMap,
unresolved: Dict[str, List[str]],
) -> None:
if not node.docstring:
return
def handler(match):
ref = match.group("ref")
parens = match.group("parens") or ""
trailing = (match.group("trailing") or "").lstrip("#")
# Remove the dot from the ref if its trailing (it is probably just
# the end of the sentence).
has_trailing_dot = False
if trailing and trailing.endswith("."):
trailing = trailing[:-1]
has_trailing_dot = True
elif not parens and ref.endswith("."):
ref = ref[:-1]
has_trailing_dot = True
href = resolver.resolve_ref(node, ref)
if href:
result = "[`{}`]({})".format(ref + parens + trailing, href)
else:
uid = ".".join(x.name for x in reverse.path(node))
unresolved.setdefault(uid, []).append(ref)
result = "`{}`".format(ref + parens)
# Add back the dot.
if has_trailing_dot:
result += "."
return result
node.docstring = re.sub(
r"\B:obj:`(?P<ref>[\w\d\._]+)(?P<parens>\(\))?(?P<trailing>#[\w\d\._]+)?`",
handler,
node.docstring,
)