Sphinx cross referencing breaks for inherited objects imported and documented in a parent module
<p>I'm trying to get my Sphinx documentation build correctly and have cross-references (including those from inherited relations) work right.</p>

<p>In my project, I have a situation which is depicted in the example below, which I replicated for convenience on <a href="https://github.com/anjos/sphinx-broken-xref" rel="nofollow">this github repo</a>:</p>

<pre><code>$ tree .
.
âââ a
âÂ Â  âââ b
âÂ Â  âÂ Â  âââ __init__.py
âÂ Â  âââ __init__.py
âââ conf.py
âââ index.rst
âââ README.md
</code></pre>

<p>In <code>a.b.__init__</code>, I declare classes <code>A</code> and <code>B</code>. <code>B</code> inherits from <code>A</code>. In <code>a.__init__</code>, I import <code>A</code> and <code>B</code> like: <code>from .b import A, B</code>. 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.</p>

<p>Then, in my rst files, I <em>autodoc</em> module <code>a</code> with <code>.. automodule:: a</code>. Because <code>a.b</code> is just an auxiliary module, I don't <em>autodoc</em> 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 <code>show-inheritance</code> expecting <code>a.B</code> will have a back link to <code>a.A</code>.</p>

<p>If I try to sphinx-build this in nit-picky mode, I'll get the following warning:</p>

<pre><code>WARNING: py:class reference target not found: a.b.A
</code></pre>

<p>If I look at the generated documentation for class <code>B</code>, then I verify it is not properly linked against class <code>A</code>, which just confirms the warning above.</p>

<p>Question: how do I fix this?</p>

<p>Sphinx uses the value of the <code>__module__</code> attribute to figure out the name of the module in which a class/function/method was defined (see <a href="https://docs.python.org/2/reference/datamodel.html#the-standard-type-hierarchy" rel="nofollow">https://docs.python.org/2/reference/datamodel.html#the-standard-type-hierarchy</a>). Sometimes this is not what you want in the documentation. </p>

<p>The attribute is writable. Your problem can be fixed by adding this line in a/__init__.py: </p>

<pre><code>A.__module__ = "a"
</code></pre>

python python-sphinx