Python: 如何在包级帮助菜单中嵌入所有文档字符串帮助？

Question

我想问的是：

TLDR：如何让我的包的帮助包含所有底层文档字符串？
我创建了一个包。该包具有所有正确的 __init__.py 文件和所有正确的文档字符串（模块、函数、class 和方法级别的文档字符串）。但是，当我执行 help(mypackage) 时，提供的唯一帮助是在顶层 __init__.py 模块提供的帮助。

通常包级帮助不包括所有底层文档字符串，但有时它会。

我想确保我嵌入了所有底层文档字符串。

例如，在 numpy package 中，所有底层文档字符串都可以在命令提示符的帮助中找到，即使它们没有在顶层 __init__.py.

中提供

也就是说，我可以输入

>>> help(numpy)

并查看所有文档，包括在 dunder init 模块之外定义的文档。

但是，许多其他软件包，包括 pandas package 等流行的软件包，并未捕获所有底层文档。

即输入

>>> help(pandas)

仅向我提供了 __init__.py 中定义的文档。

我想创建包级文档镜像 numpy 是如何做到的。

我试图浏览 numpy 以了解它是如何施展这种魔法的，但没有成功。我已经执行了 Google 搜索，但似乎没有办法对这个问题进行措辞并获得任何像样的链接。

Answer 1

numpy 向您显示有关类的文档以及在 __init__.py 模块外定义的函数，因为它们的名称已添加到 __init__.py 中的 __all__ 变量中。尝试注释第 169-173 行（不要忘记取消注释！）：

#__all__.extend(['__version__', 'show_config'])
#__all__.extend(core.__all__)
#__all__.extend(_mat.__all__)
#__all__.extend(lib.__all__)
#__all__.extend(['linalg', 'fft', 'random', 'ctypeslib', 'ma'])

执行此操作后 help(numpy) 的输出将非常有限。

我们也重现此行为。从 '/some/path' 开始，创建文件夹 folder，其中包含名为 file.py 的文件，内容如下：

class Class:
    """Class docstring"""

和__init__.py：

from .file import *

现在看看帮助：

/some/path$ python3.5
>>> import folder
>>> help(folder)

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

FILE
    /some/path/folder/__init__.py

现在将此行添加到 __init__.py:

__all__ = ['Class']

重新导入 folder 后，命令 help(folder) 将包含有关 class Class 的信息，其中包括您的文档字符串：

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

CLASSES
    builtins.object
        folder.file.Class

    class Class(builtins.object)
     |  Class docstring
     |  
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

DATA
    __all__ = ['Class']

FILE
    /some/path/folder/__init__.py

Python: 如何在包级帮助菜单中嵌入所有文档字符串帮助？

Python: how to embed all docstring help at package level help menu?

python

numpy

docstring

package

code-documentation