Feature: enhance autoclass:: to use the docstring of __new__

The method new is an alternative to __init__, but autoclass does not 
respect __new__. This commit enhances the directive autoclass:: to try
__new__ method's docstring, if __init__ method's docstring is missing or
empty.

The commit also adds tests and updates the documentation.

1 files changed, 33 insertions, 0 deletions

diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 5c2bc7ff5..068cf1da0 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -297,6 +297,9 @@ def test_get_doc():
         """Class docstring"""
         def __init__(self):
             """Init docstring"""
+
+        def __new__(cls):
+            """New docstring"""
     directive.env.config.autoclass_content = 'class'
     assert getdocl('class', C) == ['Class docstring']
     directive.env.config.autoclass_content = 'init'
@@ -380,6 +383,36 @@ def test_get_doc():
         directive.env.config.autoclass_content = 'both'
         assert getdocl('class', G) == ['Class docstring']
 
+    # class has __new__ method with docstring
+    # class docstring: depends on config value which one is taken
+    class H:
+        """Class docstring"""
+        def __init__(self):
+            pass
+
+        def __new__(cls):
+            """New docstring"""
+    directive.env.config.autoclass_content = 'class'
+    assert getdocl('class', H) == ['Class docstring']
+    directive.env.config.autoclass_content = 'init'
+    assert getdocl('class', H) == ['New docstring']
+    directive.env.config.autoclass_content = 'both'
+    assert getdocl('class', H) == ['Class docstring', '', 'New docstring']
+
+    # class has __init__ method without docstring and
+    # __new__ method with docstring
+    # class docstring: depends on config value which one is taken
+    class I:
+        """Class docstring"""
+        def __new__(cls):
+            """New docstring"""
+    directive.env.config.autoclass_content = 'class'
+    assert getdocl('class', I) == ['Class docstring']
+    directive.env.config.autoclass_content = 'init'
+    assert getdocl('class', I) == ['New docstring']
+    directive.env.config.autoclass_content = 'both'
+    assert getdocl('class', I) == ['Class docstring', '', 'New docstring']
+
 
 @with_setup(setup_test)
 def test_docstring_processing():