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

Question

我想问的是:

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

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

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

---

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

也就是说，我可以打字

>>> help(numpy)

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

但是，许多其他软件包，包括流行的软件包，如 pandas package不要捕获所有基础文档。

即打字

>>> help(pandas)

只提供了__init__.py中定义的文档。

我想创建包级文档来反射(reflect) numpy 的工作方式。

---

我试图通过 numpy 查看它是如何执行这种魔法的，但没有成功。我已经进行了谷歌搜索，但似乎没有办法用措词来表达这个问题并获得任何像样的链接。

Answer 1

numpy 向您显示有关在 __init__.py 模块外定义的类和函数的文档，因为将它们的名称添加到 中的 __all__ 变量__init__.py。尝试注释第 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