Reference target not found in specific cases

[theOehrly]

I've had some issues with reference targets not being found in the summary table. This happens in multiple of my projects, but within each project, the problem was limited to some modules only. This is a bit annoying because you can't just click an object in the summary table and jump directly to its full documentation.

I think I've found the cause for the issue now. Let me give an example project structure.

my_module
├─ submodule1
├─ submodule2

submodule1.py

class MyClass1:
    pass

submodule1.rst

.. automodule:: my_module.submodule1
    :members:
    :autosummary:

This will generate the following output:

.. py:module:: my_module.submodule1
**Classes:**
.. autosummary::
    ~my_module.submodule1.MyClass1

[...]

Everything works fine and all reference targets are found, until I add an import statement like import my_module.submodule2 to submodule1.py. Why and how the in-code imports break the reference targets is something that I don't fully understand. But as soon as I import some other module from my own package, the reference targets in the module that contains the import statement are no longer found.

I've found that reference targets work correctly if I make a minor change to autodocsumm.

autodocsumm/autodocsumm/__init__.py

Lines 305 to 308 in 255292a

	for (documenter, _) in documenters:
	self.add_line(
	indent + '~' + documenter.fullname, sourcename)
	self.add_line('', sourcename)

By changing Line 307 to indent + documenter.object_name, sourcename), reference targets work correctly for module and class summaries in all cases that I have tested.

The generated output after this is

.. py:module:: my_module.submodule1
**Classes:**
.. autosummary::
    MyClass1

[...]

The visual representation of the summary table does not change because of this.

Edit: I forgot, this on Python 3.8 with Sphinx v4.4.0

[Chilipp]

hi @theOehrly! thanks for reporting this issue. I think this is a known and so far unsolved bug in the autosummary extension, see #65

[theOehrly]

Ok, I now understand what the actual problem here is.
Have you seen sphinx-doc/sphinx#6792 though? The PR intended to fix this issue too. But this was marked as won't fix, stating that the behaviour is as intended. I too am inclined to say this is a bug in sphinx. But if the sphinx maintainers stick to that opinion, then it might be better to fix it here?

[Chilipp]

Hey @theOehrly

Sure, but I don't know if this is possible without reimplementing the autosummary extension. Did you already had a look how to potentially fix this issue here and could make some suggestions?

[theOehrly]

Hey @theOehrly

Sure, but I don't know if this is possible without reimplementing the autosummary extension. Did you already had a look how to potentially fix this issue here and could make some suggestions?

Hi, I don't have any good ideas for a potential fix right now. I will take a closer look at it some time in the next few weeks.

[Chilipp]

@theOehrly this is fixed by #70, isn't it?

[theOehrly]

@theOehrly this is fixed by #70, isn't it?

Yes, it is