From 642686159fb18fb3eec00563aa4773b941dad5bb Mon Sep 17 00:00:00 2001
From: Juan Carrano <juan.carrano@ebee.berlin>
Date: Fri, 21 Aug 2020 13:53:36 +0200
Subject: [PATCH 1/2] autodoc: Test the signature of typing.Generic subclasses.

This test is currently failing because typing.Generic.__new__ clobbers the
real signature.
---
 .../test-ext-autodoc/target/generic_class.py     | 12 ++++++++++++
 tests/test_ext_autodoc.py                        | 16 ++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 tests/roots/test-ext-autodoc/target/generic_class.py

diff --git a/tests/roots/test-ext-autodoc/target/generic_class.py b/tests/roots/test-ext-autodoc/target/generic_class.py
new file mode 100644
index 00000000000..cf4c5ed37ef
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/generic_class.py
@@ -0,0 +1,12 @@
+from typing import TypeVar, Generic
+
+
+T = TypeVar('T')
+
+
+# Test that typing.Generic's __new__ method does not mask our class'
+# __init__ signature.
+class A(Generic[T]):
+    """docstring for A"""
+    def __init__(self, a, b=None):
+        pass
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index 90a2ec95a37..e90125ba97e 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -290,6 +290,22 @@ def foo3(self, d='\n'):
         '(b, c=42, *d, **e)'
 
 
+@pytest.mark.skipif(sys.version_info < (3, 5), reason='typing is available since python3.5.')
+@pytest.mark.xfail
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodoc_process_signature_typing_generic(app):
+    actual = do_autodoc(app, 'class', 'target.generic_class.A', {})
+
+    assert list(actual) == [
+        '',
+        '.. py:class:: A(a, b=None)',
+        '   :module: target.generic_class',
+        '',
+        '   docstring for A',
+        '',
+    ]
+
+
 def test_autodoc_process_signature_typehints(app):
     captured = []
 

From 740be7f2a5c03c0bbfd96420843074c1c5cb6c10 Mon Sep 17 00:00:00 2001
From: Juan Carrano <juan.carrano@ebee.berlin>
Date: Fri, 21 Aug 2020 14:00:48 +0200
Subject: [PATCH 2/2] autodoc: blacklist typing.Generic.__new__

When documenting classes derived from typing.Generic (essentially all classes in the
typing module) the constructor signature would show an unhelpful (*args, **kwds).

typing.Generic has a __new__ method which was picked up by sphinx. With this patch it
is skipped and constructor signatures for generic classes are shown as they should.
---
 sphinx/ext/autodoc/__init__.py | 11 +++++++++++
 tests/test_ext_autodoc.py      |  1 -
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index b61a96c8494..05681ea5eb9 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1317,6 +1317,12 @@ def format_args(self, **kwargs: Any) -> Any:
 ]
 
 
+# Types whose __new__ signature is a pass-thru.
+_CLASS_NEW_BLACKLIST = [
+    'typing.Generic.__new__',
+]
+
+
 class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type: ignore
     """
     Specialized Documenter subclass for classes.
@@ -1385,6 +1391,11 @@ def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
 
         # Now we check if the 'obj' class has a '__new__' method
         new = get_user_defined_function_or_method(self.object, '__new__')
+
+        if new is not None:
+            if "{0.__module__}.{0.__qualname__}".format(new) in _CLASS_NEW_BLACKLIST:
+                new = None
+
         if new is not None:
             self.env.app.emit('autodoc-before-process-signature', new, True)
             try:
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index e90125ba97e..904107efe5a 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -291,7 +291,6 @@ def foo3(self, d='\n'):
 
 
 @pytest.mark.skipif(sys.version_info < (3, 5), reason='typing is available since python3.5.')
-@pytest.mark.xfail
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_autodoc_process_signature_typing_generic(app):
     actual = do_autodoc(app, 'class', 'target.generic_class.A', {})