python - 如何在没有模块名称的情况下记录类？

Question

我正在尝试记录一个 python 包sphinx并成功生成了 html 文件。我正在记录的包由一组文件组成*.py，其中大多数包含一个类，其中几个文件是定义了函数的真正模块。我不需要公开每个类都在一个模块中的事实，所以我from在文件中添加了合适的语句，__init__.py例如

from base import Base

这样用户就可以使用该import pkg命令，而不必指定包含该类的模块：

import pkg
class MyBase(pkg.Base):  # instead of pkg.base.Base ...
...

问题是 sphinx 坚持将类记录为pkg.base.Base. 我试图设置add_module_names = Falsein conf.py。然而，这会导致 sphinx 将类显示为简单Base而不是pkg.Base. 此外，这也破坏了作为模块的几个*.py文件的文档。

我如何sphinx将课程显示为pkg.Base？以及如何add_module_names为每个*.py文件选择性地设置指令？

Answer 1

这是完成OP要求的一种方法：

1. 在 中添加__all__列表pkg/__init__.py：

   from base import Base    # Or use 'from base import *'
   
   __all__ = ["Base"]
   

2. .. automodule:: pkg在 .rst 文件中使用。

Sphinx 现在将输出文档，其中类名显示为pkg.Base而不是pkg.base.Base.

Answer 2

我已经将我找到的答案合并到一个可扩展的外形尺寸中：

my_project/
    __init__.py
    mess.py

• mess.py：

class MyClass:
    pass

class MyOtherClass(MyClass):
    pass

• __init__.py：

from .mess import MyClass, MyOtherClass

__all_exports = [MyClass, MyOtherClass]

for e in __all_exports:
    e.__module__ = __name__

__all__ = [e.__name__ for e in __all_exports]

这对我来说似乎效果很好。

Answer 3

我想提供一个更通用的方法。

变量__all__基于 填充dir()。但子包名称（此处mypackage）和所有内置属性（以 开头__）被忽略。

from .mypackage import *

__all__ = []
for v in dir():
    if not v.startswith('__') and v != 'mypackage':
        __all__.append(v)

Answer 4

简短的回答：你不应该。只需将狮身人面像指向您的代码目录即可。Sphinx 记录代码并显示模块层次结构。最终如何导入模块完全取决于开发人员，而不是文档工具的责任。