automodule fails if path contains an certain names

[kconnour]

Describe the bug

If I mock an import using autodoc_mock_imports in my conf.py and a mocked import is a package I try to document using automodule, it will fail to document anything. Some classes documented in this way using autoclass will say the class in question is an alias of its module; other times it will work correctly. From my brief tests, autofunction works correctly.

How to Reproduce

Suppose I have a package named foobar containing module observation that contains classes classA and classB. My conf.py is in a folder on the same level as foobar. If I mock foobar, the relevant part of conf.py looks like the following

import os
import sys

sys.path.insert(0, os.path.abspath('../'))
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode'
]
autodoc_mock_imports = ['foobar']

My index.rst file looks like

.. automodule:: foobar.observation

.. autoclass:: foobar.observation.classA
   :members:

.. autoclass:: foobar.observation.classB
   :members:

When I generate documentation, it will display nothing from the automodule directive. It will display alias of foobar.observation. as the output to classA. It will correctly display classB. Curiously enough, the "source" button in the output documentation still links to the code, suggesting Sphinx is finding classA but just not documenting it.

If I simply remove 'foobar' from autodoc_mock_imports then this issue vanishes. See the attached screenshots for rendered output where I include my package name in the mocked imports, and a screenshot of the same code with that string removed from the mocked imports.

Expected behavior

I expect the two cases described above to return the same output.

Your project

https://github.com/kconnour/autodoc_issue

Screenshots

r/autodoc_issue

OS

Ubuntu 20.10

Python version

3.9

Sphinx version

4.1.1

Sphinx extensions

sphinx.ext.autodoc, sphinx.ext.napoleon, sphinx.ext.viewcode

Extra tools

No response

Additional context

No response

[kconnour]

I apologize for raising the wrong issue the first time... I thought I had tracked down the bug but I was mistaken.

This is a very easy issue to workaround: just remove the unnecessary mocked import. I just raise this issue because the output seems very strange. When I first encountered this in my code, it properly documented 5/6 classes so I was convinced Sphinx just didn't like the name of one of my classes.

[tk0miya]

What do you expect if the mocked object is given?

[kconnour]

I'm not sure I understand the question. I expect that if Sphinx finds the source code from ClassA (which it does, given that the "source" button links to the code) it will be able to document that class. I also expect whatever it does for ClassA, it will do for ClassB---if it fails to document ClassA I think it should fail to document ClassB, but the fact that ClassA fails but ClassB succeeds confuses me.

Note that I only encountered this issue because I made a mistake and forgot to remove my package's mock (I'm not suggesting mocking a package in this scenario is a good idea at all). I just thought this caused extremely strange behavior and took me some time to track down why Sphinx was behaving the way it was.

[tk0miya]

In my understanding, your case happened from a mistake. So I guess nobody would like to document the mocked object via autodoc and viewcode extensions. Is my guess correct? Or, you really want to document foobar.observation.ClassA in mocked, and create a link to the source code?

I just thought this caused extremely strange behavior and took me some time to track down why Sphinx was behaving the way it was.

IMO, it's better to emit a warning if autodoc detects a mocked object. I hope it will help resolving your case.

[kconnour]

In my understanding, your case happened from a mistake. So I guess nobody would like to document the mocked object via autodoc and viewcode extensions. Is my guess correct?

Yep, it was my mistake. I can't speak for everyone but I certainly don't actively want to document a mocked object.

IMO, it's better to emit a warning if autodoc detects a mocked object. I hope it will help resolving your case.

That'd be great!