Fix docstring preparation with included signature: ignore indentation of two lines when looking for the signature.

sphinx/ext/autodoc.py

@@ -412,15 +412,15 @@ class Documenter(object):
             # etc. don't support a prepended module name
             self.add_line(u'   :module: %s' % self.modname, '<autodoc>')
 
-    def get_doc(self, encoding=None):
+    def get_doc(self, encoding=None, ignore=1):
         """Decode and return lines of the docstring(s) for the object."""
         docstring = self.get_attr(self.object, '__doc__', None)
         # make sure we have Unicode docstrings, then sanitize and split
         # into lines
         if isinstance(docstring, unicode):
-            return [prepare_docstring(docstring)]
+            return [prepare_docstring(docstring, ignore)]
         elif docstring:
-            return [prepare_docstring(force_decode(docstring, encoding))]
+            return [prepare_docstring(force_decode(docstring, encoding), ignore)]
         return []
 
     def process_doc(self, docstrings):
@@ -834,7 +834,7 @@ class DocstringSignatureMixin(object):
     """
 
     def _find_signature(self, encoding=None):
-        docstrings = Documenter.get_doc(self, encoding)
+        docstrings = Documenter.get_doc(self, encoding, 2)
         if len(docstrings) != 1:
             return
         doclines = docstrings[0]
@@ -857,11 +857,11 @@ class DocstringSignatureMixin(object):
         setattr(self, '__new_doclines', doclines[i:])
         return args, retann
 
-    def get_doc(self, encoding=None):
+    def get_doc(self, encoding=None, ignore=1):
         lines = getattr(self, '__new_doclines', None)
         if lines is not None:
             return [lines]
-        return Documenter.get_doc(self, encoding)
+        return Documenter.get_doc(self, encoding, ignore)
 
     def format_signature(self):
         if self.args is None and self.env.config.autodoc_docstring_signature:
@@ -978,7 +978,7 @@ class ClassDocumenter(ModuleLevelDocumenter):
                 self.add_line(_(u'   Bases: %s') % ', '.join(bases),
                               '<autodoc>')
 
-    def get_doc(self, encoding=None):
+    def get_doc(self, encoding=None, ignore=1):
         content = self.env.config.autoclass_content
 
         docstrings = []

sphinx/util/docstrings.py

@@ -12,26 +12,29 @@
 import sys
 
 
-def prepare_docstring(s):
-    """Convert a docstring into lines of parseable reST.
+def prepare_docstring(s, ignore=1):
+    """Convert a docstring into lines of parseable reST.  Remove common leading
+    indentation, where the indentation of a given number of lines (usually just
+    one) is ignored.
 
-    Return it as a list of lines usable for inserting into a docutils ViewList
-    (used as argument of nested_parse().)  An empty line is added to act as a
-    separator between this docstring and following content.
+    Return the docstring as a list of lines usable for inserting into a docutils
+    ViewList (used as argument of nested_parse().)  An empty line is added to
+    act as a separator between this docstring and following content.
     """
     lines = s.expandtabs().splitlines()
-    # Find minimum indentation of any non-blank lines after first line.
+    # Find minimum indentation of any non-blank lines after ignored lines.
     margin = sys.maxint
-    for line in lines[1:]:
+    for line in lines[ignore:]:
         content = len(line.lstrip())
         if content:
             indent = len(line) - content
             margin = min(margin, indent)
-    # Remove indentation.
-    if lines:
-        lines[0] = lines[0].lstrip()
+    # Remove indentation from ignored lines.
+    for i in range(ignore):
+        if i < len(lines):
+            lines[i] = lines[i].lstrip()
     if margin < sys.maxint:
-        for i in range(1, len(lines)): lines[i] = lines[i][margin:]
+        for i in range(ignore, len(lines)): lines[i] = lines[i][margin:]
     # Remove any leading blank lines.
     while lines and not lines[0]:
         lines.pop(0)

tests/test_autodoc.py

@@ -593,8 +593,8 @@ class Outer(object):
 
 class DocstringSig(object):
     def meth(self):
-        """
-        meth(FOO, BAR=1) -> BAZ
+        """meth(FOO, BAR=1) -> BAZ
+First line of docstring
 
         rest of docstring
         """