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)