showdoc

在 notebook 和网站中显示符号文档

渲染 docment 表格

渲染格式优美的表格，显示任意函数或方法的 docments。

源代码

DocmentTbl

 DocmentTbl (obj, verbose=True, returns=True)

计算 docment 表格字符串

DocmentTbl 可以渲染一个 markdown 表格，如果合适，会显示 docments。这是一个函数 docments 表格如何渲染的示例。

def _f(a,      # description of param a
       b=True, # description of param b
       c:str=None
       ) -> int: ...

_dm = DocmentTbl(_f)
_dm
类型 默认值 详情
a 参数 a 的描述
b bool True 参数 b 的描述
c str None
返回值 int

如果表格中有一列没有信息，例如没有默认值，则该列将不显示。在下面的示例中，不显示默认值列。此外，如果函数返回值没有注解，则不渲染返回值行。

def _f(a,
        b, #param b
        c  #param c
       ): ...

_dm2 = DocmentTbl(_f)
_dm2
详情
a
b 参数 b
c 参数 c

DocmentTbl 也适用于类。默认情况下，将渲染 __init__。

class _Test:
    def __init__(self,
                 a,      # description of param a
                 b=True, # description of param b
                 c:str=None):
        ...

    def foo(self,
            c:int,      # description of param c
            d=True, # description of param d
           ):
        ...
DocmentTbl(_Test)
类型 默认值 详情
a 参数 a 的描述
b bool True 参数 b 的描述
c str None

您也可以传递一个方法进行渲染。

DocmentTbl(_Test.foo)
类型 默认值 详情
c int 参数 c 的描述
d bool True 参数 d 的描述

对象的文档

渲染签名以及 docments，以显示对象的完整文档。

源代码

ShowDocRenderer

 ShowDocRenderer (sym, name:str|None=None, title_level:int=3)

显示 sym 的文档

源代码

BasicMarkdownRenderer

 BasicMarkdownRenderer (sym, name:str|None=None, title_level:int=3)

show_doc 的 Markdown 渲染器

源代码

show_doc

 show_doc (sym, renderer=None, name:str|None=None, title_level:int=3)

显示 sym 的签名和 docstring

类型 默认值 详情
sym 要文档化的符号
renderer NoneType None 可选渲染器（默认为 markdown）
name str | None None 可选地覆盖显示的 sym 名称
title_level int 3 用于符号名称的标题级别

您可以使用 show_doc 来文档化函数、类或方法的 api。

Numpy Docstrings

如果您有 numpy docstrings 而不是 docments，show_doc 将尝试解析并像处理 docments 一样渲染它们。

警告

Numpy docstring 格式非常严格。如果您的 docstring 不严格遵守 numpy 格式，将无法正确解析，并且有关参数和返回值的**信息可能无法**正确地渲染在签名下方的表格中。在可能的情况下，我们建议使用 docments 来注解您的函数。

类上的 show_doc

show_doc 也适用于类，包括在使用 @patch 时。

您可以使用 @patch 为类 Foo 定义方法，这便于您在 notebook 中分解代码以进行文档编写。

类属性也适用于 showdoc。

可插拔的渲染器

您可以用自定义渲染器替换默认的 markdown show_doc 渲染器。例如，nbdev 提供了一个使用原始 HTML 进行渲染的简单示例。

源代码

BasicHtmlRenderer

 BasicHtmlRenderer (sym, name:str|None=None, title_level:int=3)

show_doc 的 HTML 渲染器

源代码

doc

 doc (elt)

显示 show_doc 信息以及文档链接

源代码

showdoc_nm

 showdoc_nm (tree)

获取 showdoc 的完全限定名称。

其他辅助函数

源代码