Can control how __init__ docstring is displayed

.gitignore

@@ -13,3 +13,4 @@ _api_
 .eggs
 .ropeproject/
 .cache
+.pytest_cache/

autoapi/extension.py

@@ -208,6 +208,7 @@ def setup(app):
     app.add_config_value('autoapi_add_api_root_toctree', False, 'html')
     app.add_config_value('autoapi_template_dir', None, 'html')
     app.add_config_value('autoapi_include_summaries', False, 'html')
+    app.add_config_value('autoapi_python_class_content', 'class', 'html')
     app.add_stylesheet('autoapi.css')
     directives.register_directive('autoapi-nested-parse', NestedParse)
     directives.register_directive('autoapisummary', AutoapiSummary)

autoapi/mappers/python.py

@@ -83,8 +83,13 @@ class PythonSphinxMapper(SphinxMapperBase):
         except KeyError:
             self.app.warn("Unknown type: %s" % data['type'])
         else:
-            obj = cls(data, jinja_env=self.jinja_env,
-                      options=self.app.config.autoapi_options, **kwargs)
+            obj = cls(
+                data,
+                jinja_env=self.jinja_env,
+                options=self.app.config.autoapi_options,
+                class_content=self.app.config.autoapi_python_class_content,
+                **kwargs
+            )
 
             lines = sphinx.util.docstrings.prepare_docstring(obj.docstring)
             try:
@@ -124,7 +129,7 @@ class PythonPythonMapper(PythonMapperBase):
     language = 'python'
     is_callable = False
 
-    def __init__(self, obj, **kwargs):
+    def __init__(self, obj, class_content='class', **kwargs):
         super(PythonPythonMapper, self).__init__(obj, **kwargs)
 
         self.name = obj['name']
@@ -137,6 +142,7 @@ class PythonPythonMapper(PythonMapperBase):
 
         # For later
         self.item_map = collections.defaultdict(list)
+        self._class_content = class_content
 
     @property
     def args(self):
@@ -146,6 +152,14 @@ class PythonPythonMapper(PythonMapperBase):
     def args(self, value):
         self._args = value
 
+    @property
+    def docstring(self):
+        return self._docstring
+
+    @docstring.setter
+    def docstring(self, value):
+        self._docstring = value
+
     @property
     def is_undoc_member(self):
         return not bool(self.docstring)
@@ -198,6 +212,13 @@ class PythonMethod(PythonPythonMapper):
     is_callable = True
     ref_directive = 'meth'
 
+    @property
+    def display(self):
+        if self.short_name == '__init__':
+            return False
+
+        return super(PythonMethod, self).display
+
 
 class PythonData(PythonPythonMapper):
     """Global, module level data."""
@@ -275,16 +296,31 @@ class PythonClass(PythonPythonMapper):
     def args(self):
         args = self._args
 
-        for child in self.children:
-            if child.short_name == '__init__':
-                args = child.args
-                break
+        constructor = self.constructor
+        if constructor:
+            args = constructor.args
 
         if args.startswith('self'):
             args = args[4:].lstrip(',').lstrip()
 
         return args
 
+    @PythonPythonMapper.docstring.getter
+    def docstring(self):
+        docstring = super(PythonClass, self).docstring
+
+        if self._class_content in ('both', 'init'):
+            constructor_docstring = self.constructor_docstring
+            if constructor_docstring:
+                if self._class_content == 'both':
+                    docstring = '{0}\n{1}'.format(
+                        docstring, constructor_docstring,
+                    )
+                else:
+                    docstring = constructor_docstring
+
+        return docstring
+
     @property
     def methods(self):
         return self._children_of_type('method')
@@ -293,6 +329,29 @@ class PythonClass(PythonPythonMapper):
     def attributes(self):
         return self._children_of_type('attribute')
 
+    @property
+    def constructor(self):
+        for child in self.children:
+            if child.short_name == '__init__':
+                return child
+
+        return None
+
+    @property
+    def constructor_docstring(self):
+        docstring = ''
+
+        constructor = self.constructor
+        if constructor and constructor.docstring:
+            docstring = constructor.docstring
+        else:
+            for child in self.children:
+                if child.short_name == '__new__':
+                    docstring = child.docstring
+                    break
+
+        return docstring
+
 
 class Parser(object):
     def parse_file(self, file_path):

docs/config.rst

@@ -63,6 +63,21 @@ Customization Options
 
 	Whether include autosummary directives in generated module documentation.
 
+.. confval:: autoapi_python_class_content
+
+	Default: ``class``
+
+	Which docstring to insert into the content of the class.
+
+	:param class: Use only the class docstring.
+	:param both: Use the concatentation of the class docstring and the
+	``__init__``/``__new__`` docstring.
+	:param init: Use only the ``__init__``/``__new__`` docstring.
+
+	If the class does not have an ``__init__`` or the ``__init__``
+	docstring is empty and the class defines a ``__new__`` with a docstring,
+	the ``__new__`` docstring is used instead of the ``__init__`` docstring.
+
 Debugging Options
 -----------------
 

tests/pyexample/example/example.py

@@ -25,6 +25,7 @@ class Foo(object):
             return True
 
     def __init__(self, attr):
+        """Constructor docstring"""
         self.attr = attr
         self.attr2 = attr
         """This is the docstring of an instance attribute.

tests/test_integration.py

@@ -172,6 +172,43 @@ class PythonTests(LanguageIntegrationTests):
                 example_file
             )
 
+    def _test_class_content(self, class_content):
+        confoverrides={
+            'autoapi_python_class_content': class_content,
+        }
+
+        with sphinx_build('pyexample', confoverrides=confoverrides):
+            example_path = '_build/text/autoapi/example/index.txt'
+            with io.open(example_path, encoding='utf8') as example_handle:
+                example_file = example_handle.read()
+
+                assert_class = self.assertIn
+                if class_content == 'init':
+                    assert_class = self.assertNotIn
+
+                assert_class(
+                    'Can we parse arguments',
+                    example_file
+                )
+
+                assert_init = self.assertIn
+                if class_content not in ('both', 'init'):
+                    assert_init = self.assertNotIn
+
+                assert_init(
+                    'Constructor docstring',
+                    example_file
+                )
+
+    def test_class_class_content(self):
+        self._test_class_content('class')
+
+    def test_both_class_content(self):
+        self._test_class_content('both')
+
+    def test_init_class_content(self):
+        self._test_class_content('init')
+
 
 class DotNetTests(LanguageIntegrationTests):