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 

$ 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: 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. If I *autodoc* module `a.b` instead, it will work, but my 
documentation will not show the shortcuts I intended when I wrote the 

Is there a fix for this without *autodoc*'ing module `a.b`? I.e., keeping 
the imports in the way they are?

Thanks for any tip.

[2] https://github.com/anjos/sphinx-broken-xref
[3] https://github.com/sphinx-doc/sphinx/issues/3048

You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To post to this group, send email to sphinx-users@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Reply via email to