def parse_function(self, func: Callable, parser: argparse.ArgumentParser) -> None:
sig = inspect.signature(func)
arg_docs = {}
docs = parse_docstring(func.__doc__)
for opt in docs.params:
if opt.description:
arg_docs[opt.arg_name] = opt.description
for arg in sig.parameters:
if arg == "self":
continue
help_doc = arg_docs.get(arg)
args, kwargs = self.parse_param(arg, sig.parameters[arg], help_doc=help_doc)
parser.add_argument(*args, **kwargs)
def _generate_class_doc(self, class_node: Class,
context: ParsoGeneratorContext):
yield markdown_heading(class_node.name.value, level=context.depth)
doc_node = cast(Optional[String], class_node.get_doc_node())
if doc_node:
doc = parse_docstring(doc_node._get_payload())
yield markdown_paragraph(doc.short_description)
yield markdown_paragraph(doc.long_description)
if context.deep:
for child_node in iter_children(class_node):
yield from self._generate_doc(child_node,
context.set_parent(class_node))
def _generate_module_doc(self, module_node: Module,
context: ParsoGeneratorContext):
module_path = context.filepath.relative_to(context.basepath).parts
if module_path[-1] == "__init__.py":
module_path = module_path[:-1]
else:
module_name, _ = os.path.splitext(module_path[-1])
module_path = module_path[:-1] + (module_name, )
yield markdown_heading(".".join(module_path), level=context.depth)
doc_node = cast(Optional[String], module_node.get_doc_node())
if doc_node:
doc = parse_docstring(doc_node._get_payload())
yield markdown_paragraph(doc.short_description)
yield markdown_paragraph(doc.long_description)
if context.deep:
for child_node in iter_children(module_node):
yield from self._generate_doc(child_node,
context.set_parent(module_node))
def get_help(self, obj: Any) -> str:
return (parse_docstring(obj.__doc__).short_description or "").strip()
def _generate_func_doc(self, func_node: Function,
context: ParsoGeneratorContext):
is_undocumented = func_node.get_doc_node() is None
is_private = re.match(r"^_[^_]+?$", func_node.name.value)
if isnode(context.parent, Class):
if not context.options["methods"]["undocumented"]:
if is_undocumented:
return
if not context.options["methods"]["private"]:
if is_private:
return
is_constructor = func_node.name.value == "__init__"
is_static = any(
re.search("(staticmethod|classmethod)",
decorator_node.get_code())
for decorator_node in func_node.get_decorators())
prefix = context.parent_name + ("." if is_static else "#")
else:
is_constructor = False
is_static = True
prefix = ""
doc_node = cast(Optional[String], func_node.get_doc_node())
if doc_node:
doc = parse_docstring(doc_node._get_payload())
else:
doc = None
param_nodes: OrderedDict[str, Param] = OrderedDict()
for idx, param_node in enumerate(func_node.get_params()):
param_name = param_node.name.value
if idx == 0 and param_name in ("self", "cls"):
continue
param_nodes[param_name] = param_node
param_docs: OrderedDict[str, DocstringParam] = OrderedDict()
if doc:
param_docs.update([(param.arg_name, param)
for param in doc.params])
param_string = ", ".join(
param_node.get_code(include_prefix=False, include_comma=False)
for param_node in param_nodes.values())
yield markdown_heading(
"`{prefix}{title}({params})`".format(
prefix=prefix,
title=func_node.name.value,
params=param_string,
),
level=context.depth,
)
if doc:
yield markdown_paragraph(doc.short_description)
decorator_nodes: List[Decorator] = func_node.get_decorators()
if decorator_nodes:
yield markdown_heading("Decorators", level=context.depth + 1)
with markdown_block() as block:
block.write('<pre><code class="language-python">')
for decorator_node in decorator_nodes:
block.writeln(
decorator_node.get_code(include_prefix=False).strip())
block.write("</code></pre>")
yield block
if param_nodes or param_docs:
yield markdown_heading("Arguments", level=context.depth + 1)
with markdown_block() as block:
block.writeln("| Name | Type | Description | Default |")
block.writeln("| ---- | ---- | ----------- | ------- |")
seen: Set[str] = set()
for param_name in chain(param_docs, param_nodes):
if param_name in seen:
continue
seen.add(param_name)
param_node = param_nodes.get(param_name)
param_doc = param_docs.get(param_name)
block.writeln(
"| {name} | {type} | {description} | {default} |".
format(
name=param_name,
type=(getattr(param_doc, "type_name", None)
or get_code(
getattr(param_node, "annotation", None))
or "-"),
description=getattr(param_doc, "description", "-"),
default=(getattr(param_doc, "default", None)
or get_code(
getattr(param_node, "default", None))
or "-"),
))
yield block
if not is_constructor:
yield markdown_heading("Returns", level=context.depth + 1)
with markdown_block() as block:
if doc:
returns_doc = doc.returns
else:
returns_doc = None
block.writeln("| Type | Description |")
block.writeln("| ---- | ----------- |")
block.writeln("| {type} | {description} |".format(
type=(getattr(returns_doc, "type_name", None)
or get_code(func_node.annotation) or "-"),
description=getattr(returns_doc, "description", None)
or "-",
))
yield block
if doc and doc.long_description:
yield markdown_heading("Details", level=context.depth + 1)
yield markdown_paragraph(doc.long_description)
