Sphinx交叉引用中断了在父模块中导入和记录的继承对象 [英] Sphinx cross referencing breaks for inherited objects imported and documented in a parent module
问题描述
我正在尝试正确构建Sphinx文档并正确使用交叉引用(包括来自继承关系的交叉引用).
在我的项目中，下面的示例描述了这种情况，为方便起见，在解决方案
Sphinx使用__module__属性的值来找出定义了类/函数/方法的模块的名称(请参见 https://docs.python.org/2/reference/datamodel. html#the-standard-type-hierarchy ).有时，这不是您在文档中想要的.
该属性是可写的.您可以通过在/__init__.py中添加以下行来解决您的问题:
A.__module__ = "a"
I'm trying to get my Sphinx documentation build correctly and have cross-references (including those from inherited relations) work right.
In my project, I have a situation which is depicted in the example below, which I replicated for convenience on this github repo:
$ tree .
.
├── a
│ ├── b
│ │ └── __init__.py
│ └── __init__.py
├── conf.py
├── index.rst
└── README.md
In a.b.__init__, I declare classes A and B. B inherits from A. In a.__init__, I import A and B like: from .b import A, B. The reason I do this in my real projects is to reduce the import paths on modules while keeping implementation of specific classes in separate files.
Then, in my rst files, I autodoc module a with .. automodule:: a. Because a.b is just an auxiliary module, I don't autodoc it since I don't want to get repeated references to the same classes and not to confuse the user on what they should be really doing. I also set show-inheritance expecting a.B will have a back link to a.A.
If I try to sphinx-build this in nit-picky mode, I'll get the following warning:
WARNING: py:class reference target not found: a.b.A
If I look at the generated documentation for class B, then I verify it is not properly linked against class A, which just confirms the warning above.
Question: how do I fix this?
Sphinx uses the value of the __module__ attribute to figure out the name of the module in which a class/function/method was defined (see https://docs.python.org/2/reference/datamodel.html#the-standard-type-hierarchy). Sometimes this is not what you want in the documentation.
The attribute is writable. Your problem can be fixed by adding this line in a/__init__.py:
A.__module__ = "a"
这篇关于Sphinx交叉引用中断了在父模块中导入和记录的继承对象的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
