Merge branch '3.4.x' into 8602_process-docstring_for_nondatadescriptors

CHANGES

@@ -16,6 +16,7 @@ Features added
 Bugs fixed
 ----------
 
+* #8164: autodoc: Classes that inherit mocked class are not documented
 * #8602: autodoc: The ``autodoc-process-docstring`` event is emitted to the
   non-datadescriptors unexpectedly
 

setup.cfg

@@ -60,6 +60,7 @@ filterwarnings =
     all
     ignore::DeprecationWarning:docutils.io
     ignore::DeprecationWarning:pyximport.pyximport
+    ignore::ImportWarning:importlib._bootstrap
     ignore::PendingDeprecationWarning:sphinx.util.pycompat
 markers =
     apidoc

sphinx/ext/autodoc/__init__.py

@@ -28,7 +28,7 @@
 from sphinx.environment import BuildEnvironment
 from sphinx.ext.autodoc.importer import (get_class_members, get_module_members,
                                          get_object_members, import_object)
-from sphinx.ext.autodoc.mock import mock
+from sphinx.ext.autodoc.mock import ismock, mock
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import inspect, logging
@@ -731,7 +731,7 @@ def is_filtered_inherited_member(name: str) -> bool:
                 isprivate = membername.startswith('_')
 
             keep = False
-            if safe_getattr(member, '__sphinx_mock__', None) is not None:
+            if ismock(member):
                 # mocked module or object
                 pass
             elif self.options.exclude_members and membername in self.options.exclude_members:

sphinx/ext/autodoc/mock.py

@@ -17,6 +17,7 @@
 from typing import Any, Generator, Iterator, List, Sequence, Tuple, Union
 
 from sphinx.util import logging
+from sphinx.util.inspect import safe_getattr
 
 logger = logging.getLogger(__name__)
 
@@ -147,3 +148,24 @@ def mock(modnames: List[str]) -> Generator[None, None, None]:
     finally:
         sys.meta_path.remove(finder)
         finder.invalidate_caches()
+
+
+def ismock(subject: Any) -> bool:
+    """Check if the object is mocked."""
+    # check the object has '__sphinx_mock__' attribute
+    if not hasattr(subject, '__sphinx_mock__'):
+        return False
+
+    # check the object is mocked module
+    if isinstance(subject, _MockModule):
+        return True
+
+    try:
+        # check the object is mocked object
+        __mro__ = safe_getattr(type(subject), '__mro__', [])
+        if len(__mro__) > 2 and __mro__[1] is _MockObject:
+            return True
+    except AttributeError:
+        pass
+
+    return False

sphinx/testing/fixtures.py

@@ -250,3 +250,15 @@ def tempdir(tmpdir: str) -> "util.path":
     this fixture is for compat with old test implementation.
     """
     return util.path(tmpdir)
+
+
+@pytest.fixture
+def rollback_sysmodules():
+    """Rollback sys.modules to before testing to unload modules during tests."""
+    try:
+        sysmodules = list(sys.modules)
+        yield
+    finally:
+        for modname in list(sys.modules):
+            if modname not in sysmodules:
+                sys.modules.pop(modname)

tests/roots/test-ext-autodoc/target/need_mocks.py

@@ -28,4 +28,9 @@ def decoratedMethod(self):
         return None
 
 
+class Inherited(missing_module.Class):
+    """docstring"""
+    pass
+
+
 sphinx.missing_module4.missing_function(len(missing_name2))

tests/test_ext_autodoc_automodule.py

@@ -0,0 +1,31 @@
+"""
+    test_ext_autodoc_autocmodule
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Test the autodoc extension.  This tests mainly the Documenters; the auto
+    directives are tested in a test source file translated by test_build.
+
+    :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import sys
+
+import pytest
+
+from .test_ext_autodoc import do_autodoc
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc',
+                    confoverrides={'autodoc_mock_imports': ['missing_module',
+                                                            'missing_package1',
+                                                            'missing_package2',
+                                                            'missing_package3',
+                                                            'sphinx.missing_module4']})
+@pytest.mark.usefixtures("rollback_sysmodules")
+def test_subclass_of_mocked_object(app):
+    sys.modules.pop('target', None)  # unload target module to clear the module cache
+
+    options = {'members': True}
+    actual = do_autodoc(app, 'module', 'target.need_mocks', options)
+    assert '.. py:class:: Inherited(*args: Any, **kwargs: Any)' in actual

tests/test_ext_autodoc_configs.py

@@ -429,7 +429,10 @@ def test_autoclass_content_and_docstring_signature_both(app):
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
+@pytest.mark.usefixtures("rollback_sysmodules")
 def test_mocked_module_imports(app, warning):
+    sys.modules.pop('target', None)  # unload target module to clear the module cache
+
     # no autodoc_mock_imports
     options = {"members": 'TestAutodoc,decoratedFunction,func'}
     actual = do_autodoc(app, 'module', 'target.need_mocks', options)

tests/test_ext_autodoc_mock.py

@@ -15,7 +15,7 @@
 
 import pytest
 
-from sphinx.ext.autodoc.mock import _MockModule, _MockObject, mock
+from sphinx.ext.autodoc.mock import _MockModule, _MockObject, ismock, mock
 
 
 def test_MockModule():
@@ -129,3 +129,19 @@ class Bar:
     assert func.__doc__ == "docstring"
     assert Foo.meth.__doc__ == "docstring"
     assert Bar.__doc__ == "docstring"
+
+
+def test_ismock():
+    with mock(['sphinx.unknown']):
+        mod1 = import_module('sphinx.unknown')
+        mod2 = import_module('sphinx.application')
+
+        class Inherited(mod1.Class):
+            pass
+
+        assert ismock(mod1) is True
+        assert ismock(mod1.Class) is True
+        assert ismock(Inherited) is False
+
+        assert ismock(mod2) is False
+        assert ismock(mod2.Sphinx) is False

tox.ini

@@ -25,7 +25,7 @@ deps =
 extras =
     test
 setenv =
-    PYTHONWARNINGS = all,ignore::ImportWarning:importlib._bootstrap_external,ignore::DeprecationWarning:site,ignore::DeprecationWarning:distutils
+    PYTHONWARNINGS = all,ignore::ImportWarning:importlib._bootstrap_external,ignore::DeprecationWarning:site,ignore::DeprecationWarning:distutils,ignore::DeprecationWarning:pip._vendor.packaging.version
     PYTEST_ADDOPTS = {env:PYTEST_ADDOPTS:} --color yes
 commands=
     python -X dev -m pytest --durations 25 {posargs}