父模块中导入和记录的继承对象的 Sphinx 交叉引用中断

Question

我正在尝试正确构建我的 Sphinx 文档并使交叉引用（包括来自继承关系的交叉引用）正常工作。

在我的项目中，我遇到了下面示例中描述的情况，为方便起见，我在 this github repo:

上复制了该示例

$ tree .
.
├── a
│   ├── b
│   │   └── __init__.py
│   └── __init__.py
├── conf.py
├── index.rst
└── README.md

在a.b.__init__中，我声明class是A和B。 B 继承自 A。在 a.__init__ 中，我导入 A 和 B，如：from .b import A, B。我在实际项目中这样做的原因是减少模块的导入路径，同时在单独的文件中保持特定 classes 的实现。

然后，在我的第一个文件中，我 autodoc 模块 a 和 .. automodule:: a。因为 a.b 只是一个辅助模块，所以我没有 autodoc 因为我不想重复引用相同的 classes 而不是使用户对他们真正应该做的事情感到困惑。我还设置了 show-inheritance 期望 a.B 将返回 link 到 a.A。

如果我尝试在吹毛求疵的模式下构建 sphinx，我会收到以下警告：

WARNING: py:class reference target not found: a.b.A

如果我查看 class B 的生成文档，然后我验证它没有正确地 link 根据 class A 编辑，这只是证实了上面的警告。

问题：我该如何解决这个问题？

Answer 1

Sphinx 使用 __module__ 属性的值来确定定义了 class/function/method 的模块的名称（参见 https://docs.python.org/2/reference/datamodel.html#the-standard-type-hierarchy）。有时这不是您在文档中想要的。

该属性是可写的。您的问题可以通过在 a/__init__.py 中添加此行来解决：

A.__module__ = "a"

父模块中导入和记录的继承对象的 Sphinx 交叉引用中断

Sphinx cross referencing breaks for inherited objects imported and documented in a parent module

python

github

python-sphinx

autodoc