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?
See Question&Answers more detail:
os 与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…