在模块文档中包含导入的函数

Question

我的代码具有以下目录结构：

apkg/
  __init__.py
  amod.py
  bmod.py
  cmod.py

其中 apkg/__init__.py 包含：

"""
effusive top-level documentation
"""
from apkg.amod import foo
from apkg.bmod import bar
from apkg.cmod import baz

并且从 python repl 我可以成功调用 foo、bar 和 baz 而不知道它们定义在哪个子模块中：

>>> import apkg
>>> apkg.foo()
"foo"

并获取他们的文档：

>>> help(apkg.foo)
Help on function foo in module apkg.amod:

foo()
    Returns "foo"

但是 apkg 的文档中没有公布它们：

>>> help(apkg)
Help on package apkg:

NAME
    apkg - effusive top-level documentation

PACKAGE CONTENTS
    amod
    bmod
    cmod

FILE
    /path/to/apkg/__init__.py

这作为默认设置是有意义的，因为我几乎不想通过在 apkg/__init__.py 中执行 from collections import defaultdict 来包含 defaultdict 的文档。

有没有办法覆盖这个默认值，这样我就可以告诉文档解析器在 help(apkg) 的函数部分列出 foo、bar 和 baz ？

Answer 1

根据this answer：

Documentation tools

Documentation and code autocompletion tools may (in fact, should) also inspect the __all__ to determine what names to show as available from a module.

所以它就像在 apkg/__init__.py

上附加一行一样简单

__all__ = ['foo', 'bar', 'baz']

在模块文档中包含导入的函数

include imported functions in module documentation

python

documentation

Documentation tools