Merge branch '3.x' into 4606_incorrect_location_of_docstring

.github/workflows/main.yml

@@ -1,9 +1,41 @@
-name: CI on Windows
+name: CI
 
 on: [push, pull_request]
 
 jobs:
-  build:
+  ubuntu:
+    runs-on: ubuntu-16.04
+    strategy:
+      fail-fast: false
+      matrix:
+        name: [py35, py36, py37]
+        include:
+        - name: py35
+          python: 3.5
+          docutils: du12
+        - name: py36
+          python: 3.6
+          docutils: du13
+        - name: py37
+          python: 3.7
+          docutils: du14
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python }}
+    - name: Check Python version
+      run: python --version
+    - name: Install graphviz
+      run: sudo apt-get install graphviz
+    - name: Install dependencies
+      run: pip install -U tox
+    - name: Run Tox
+      run: tox -e ${{ matrix.docutils }} -- -vv
+
+  windows:
     runs-on: windows-latest
     strategy:
       matrix:

.travis.yml

@@ -11,15 +11,6 @@ env:
 
 jobs:
   include:
-    - python: '3.5'
-      env:
-        - TOXENV=du12
-    - python: '3.6'
-      env:
-        - TOXENV=du13
-    - python: '3.7'
-      env:
-        - TOXENV=du14
     - python: '3.8'
       env:
         - TOXENV=du15

CHANGES

@@ -20,6 +20,7 @@ Features added
 Bugs fixed
 ----------
 
+* #7613: autodoc: autodoc does not respect __signature__ of the class
 * #4606: autodoc: the location of the warning is incorrect for inherited method
 
 Testing

sphinx/ext/autodoc/__init__.py

@@ -1400,7 +1400,12 @@ def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
         # This sequence is copied from inspect._signature_from_callable.
         # ValueError means that no signature could be found, so we keep going.
 
-        # First, let's see if it has an overloaded __call__ defined
+        # First, we check the obj has a __signature__ attribute
+        if (hasattr(self.object, '__signature__') and
+                isinstance(self.object.__signature__, Signature)):
+            return None, None, self.object.__signature__
+
+        # Next, let's see if it has an overloaded __call__ defined
         # in its metaclass
         call = get_user_defined_function_or_method(type(self.object), '__call__')
 

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

@@ -1,3 +1,6 @@
+from inspect import Parameter, Signature
+
+
 class Foo:
     pass
 
@@ -10,3 +13,11 @@ def __init__(self, x, y):
 class Baz:
     def __new__(cls, x, y):
         pass
+
+
+class Qux:
+    __signature__ = Signature(parameters=[Parameter('foo', Parameter.POSITIONAL_OR_KEYWORD),
+                                          Parameter('bar', Parameter.POSITIONAL_OR_KEYWORD)])
+
+    def __init__(self, x, y):
+        pass

tests/test_ext_autodoc.py

@@ -1832,19 +1832,26 @@ def test_autodoc_for_egged_code(app):
 def test_singledispatch(app):
     options = {"members": None}
     actual = do_autodoc(app, 'module', 'target.singledispatch', options)
-    assert list(actual) == [
-        '',
-        '.. py:module:: target.singledispatch',
-        '',
-        '',
-        '.. py:function:: func(arg, kwarg=None)',
-        '                 func(arg: int, kwarg=None)',
-        '                 func(arg: str, kwarg=None)',
-        '   :module: target.singledispatch',
-        '',
-        '   A function for general use.',
-        '',
-    ]
+    if sys.version_info < (3, 6):
+        # check the result via "in" because the order of singledispatch signatures is
+        # usually changed (because dict is not OrderedDict yet!)
+        assert '.. py:function:: func(arg, kwarg=None)' in actual
+        assert '                 func(arg: int, kwarg=None)' in actual
+        assert '                 func(arg: str, kwarg=None)' in actual
+    else:
+        assert list(actual) == [
+            '',
+            '.. py:module:: target.singledispatch',
+            '',
+            '',
+            '.. py:function:: func(arg, kwarg=None)',
+            '                 func(arg: int, kwarg=None)',
+            '                 func(arg: str, kwarg=None)',
+            '   :module: target.singledispatch',
+            '',
+            '   A function for general use.',
+            '',
+        ]
 
 
 @pytest.mark.skipif(sys.version_info < (3, 8),

tests/test_ext_autodoc_autoclass.py

@@ -0,0 +1,50 @@
+"""
+    test_ext_autodoc_autoclass
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    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 pytest
+
+from test_ext_autodoc import do_autodoc
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_classes(app):
+    actual = do_autodoc(app, 'function', 'target.classes.Foo')
+    assert list(actual) == [
+        '',
+        '.. py:function:: Foo()',
+        '   :module: target.classes',
+        '',
+    ]
+
+    actual = do_autodoc(app, 'function', 'target.classes.Bar')
+    assert list(actual) == [
+        '',
+        '.. py:function:: Bar(x, y)',
+        '   :module: target.classes',
+        '',
+    ]
+
+    actual = do_autodoc(app, 'function', 'target.classes.Baz')
+    assert list(actual) == [
+        '',
+        '.. py:function:: Baz(x, y)',
+        '   :module: target.classes',
+        '',
+    ]
+
+    actual = do_autodoc(app, 'function', 'target.classes.Qux')
+    assert list(actual) == [
+        '',
+        '.. py:function:: Qux(foo, bar)',
+        '   :module: target.classes',
+        '',
+    ]
+

tests/test_ext_autodoc_autofunction.py

@@ -9,6 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+import sys
+
 import pytest
 
 from test_ext_autodoc import do_autodoc
@@ -40,6 +42,14 @@ def test_classes(app):
         '',
     ]
 
+    actual = do_autodoc(app, 'function', 'target.classes.Qux')
+    assert list(actual) == [
+        '',
+        '.. py:function:: Qux(foo, bar)',
+        '   :module: target.classes',
+        '',
+    ]
+
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_callable(app):
@@ -108,16 +118,23 @@ def test_decorated(app):
 def test_singledispatch(app):
     options = {}
     actual = do_autodoc(app, 'function', 'target.singledispatch.func', options)
-    assert list(actual) == [
-        '',
-        '.. py:function:: func(arg, kwarg=None)',
-        '                 func(arg: int, kwarg=None)',
-        '                 func(arg: str, kwarg=None)',
-        '   :module: target.singledispatch',
-        '',
-        '   A function for general use.',
-        '',
-    ]
+    if sys.version_info < (3, 6):
+        # check the result via "in" because the order of singledispatch signatures is
+        # usually changed (because dict is not OrderedDict yet!)
+        assert '.. py:function:: func(arg, kwarg=None)' in actual
+        assert '                 func(arg: int, kwarg=None)' in actual
+        assert '                 func(arg: str, kwarg=None)' in actual
+    else:
+        assert list(actual) == [
+            '',
+            '.. py:function:: func(arg, kwarg=None)',
+            '                 func(arg: int, kwarg=None)',
+            '                 func(arg: str, kwarg=None)',
+            '   :module: target.singledispatch',
+            '',
+            '   A function for general use.',
+            '',
+        ]
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')