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

【问题标题】：Sphinx cross referencing breaks for inherited objects imported and documented in a parent module在父模块中导入和记录的继承对象的 Sphinx 交叉引用中断
【发布时间】：2016-10-13 10:38:34
【问题描述】：

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

在我的项目中，我遇到了以下示例中描述的情况，为方便起见，我在 this github repo 上进行了复制：

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

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

然后，在我的第一个文件中，我 autodoc 模块 a 和 .. automodule:: a。因为a.b 只是一个辅助模块，我不 autodoc 它因为我不想重复引用相同的类，也不想让用户混淆他们应该真正做什么.我还设置了show-inheritance 期望a.B 将有一个指向a.A 的反向链接。

如果我尝试在 nit-picky 模式下进行 sphinx-build，我会收到以下警告：

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

如果我查看为类 B 生成的文档，然后我确认它没有正确链接到类 A，这只是确认了上面的警告。

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

【问题讨论】：

如果在a/__init__.py 中添加A.__module__ = "a" 就可以了。这类似于stackoverflow.com/q/22096187/407651。
确实有效。愿意填写答案以便我指出解决方案吗？

标签： python github python-sphinx autodoc

【解决方案1】：

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

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

A.__module__ = "a"

【讨论】：

请注意，这也可以通过在类定义中设置__module__ = "a" 在类级别定义。看起来更干净一些。