Classes and methods inherit docstrings from their parent

Closes #203

CHANGELOG.rst

@@ -14,6 +14,9 @@ Features
 * `#201 <https://github.com/readthedocs/sphinx-autoapi/issues/201>`: (Python)
   Added the ``autoapi_member_order`` option to allow the order that members
   are documentated to be configurable.
+* `#203 <https://github.com/readthedocs/sphinx-autoapi/issues/203>`: (Python)
+  A class without a docstring inherits one from its parent.
+  A methods without a docstring inherits one from the method that it overrides.
 
 Bug Fixes
 ^^^^^^^^^

autoapi/mappers/python/astroid_utils.py

@@ -526,3 +526,42 @@ def format_args(args_node):  # pylint: disable=too-many-branches,too-many-statem
         result.append(kwarg_result)
 
     return ", ".join(result)
+
+
+def get_func_docstring(node):
+    """Get the docstring of a node, using a parent docstring if needed.
+
+    :param node: The node to get a docstring for.
+    :type node: astroid.nodes.FunctionDef
+    """
+    doc = node.doc
+
+    if doc is None and isinstance(node.parent, astroid.nodes.ClassDef):
+        for base in node.parent.ancestors():
+            for child in base.get_children():
+                if (
+                    isinstance(child, node.__class__)
+                    and child.name == node.name
+                    and child.doc is not None
+                ):
+                    return child.doc
+
+    return doc or ""
+
+
+def get_class_docstring(node):
+    """Get the docstring of a node, using a parent docstring if needed.
+
+    :param node: The node to get a docstring for.
+    :type node: astroid.nodes.ClassDef
+    """
+    doc = node.doc
+
+    if doc is None:
+        for base in node.ancestors():
+            if base.qname() in ("__builtins__.object", "builtins.object"):
+                continue
+            if base.doc is not None:
+                return base.doc
+
+    return doc or ""

autoapi/mappers/python/parser.py

@@ -120,7 +120,7 @@ class Parser(object):
             "full_name": self._get_full_name(node.name),
             "args": args,
             "bases": basenames,
-            "doc": self._decode(node.doc or ""),
+            "doc": self._decode(astroid_utils.get_class_docstring(node)),
             "from_line_no": node.fromlineno,
             "to_line_no": node.tolineno,
             "children": [],
@@ -188,7 +188,7 @@ class Parser(object):
             "name": node.name,
             "full_name": self._get_full_name(node.name),
             "args": arg_string,
-            "doc": self._decode(node.doc or ""),
+            "doc": self._decode(astroid_utils.get_func_docstring(node)),
             "from_line_no": node.fromlineno,
             "to_line_no": node.tolineno,
             "return_annotation": return_annotation,

tests/python/pyexample/example/example.py

@@ -105,4 +105,5 @@ def decorator_okay(func):
 
 
 class Bar(Foo):
-    pass
+    def method_okay(self, foo=None, bar=None):
+        pass

tests/python/test_pyintegration.py

@@ -79,6 +79,10 @@ class TestSimpleModule(object):
         # "self" should not be included in constructor arguments
         assert "Foo(self" not in example_file
 
+        # Overridden methods without their own docstring
+        # should inherit the parent's docstring
+        assert example_file.count("This method should parse okay") == 2
+
         assert not os.path.exists("_build/text/autoapi/method_multiline")
 
         index_path = "_build/text/index.txt"