Closes #1374: Autosummary generates overly-long summaries if first line doesn't end with a period

CHANGES

@@ -12,6 +12,8 @@ Bugs fixed
   not start with a dash or slash, and referencing them will work correctly.
 * #1358: Fix handling of image paths outside of the source directory when using
   the "wildcard" style reference.
+* #1374: Fix for autosummary generating overly-long summaries if first line
+  doesn't end with a period.
 
 Documentation
 -------------

sphinx/ext/autosummary/__init__.py

@@ -275,6 +275,16 @@ class Autosummary(Directive):
 
             while doc and not doc[0].strip():
                 doc.pop(0)
+
+            # If there's a blank line, then we can assume the first sentence /
+            # paragraph has ended, so anything after shouldn't be part of the
+            # summary
+            for i, piece in enumerate(doc):
+                if not piece.strip():
+                    doc = doc[:i]
+                    break
+
+            # Try to find the "first sentence", which may span multiple lines
             m = re.search(r"^([A-Z].*?\.)(?:\s|$)", " ".join(doc).strip())
             if m:
                 summary = m.group(1).strip()

tests/roots/test-autosummary/conf.py

@@ -0,0 +1,5 @@
+extensions = ['sphinx.ext.autosummary']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+autosummary_generate = True

tests/roots/test-autosummary/contents.rst

@@ -0,0 +1,6 @@
+
+.. autosummary::
+   :nosignatures:
+   :toctree:
+   
+   dummy_module

tests/roots/test-autosummary/dummy_module.py

@@ -0,0 +1,21 @@
+
+def withSentence():
+    '''I have a sentence which
+    spans multiple lines. Then I have
+    more stuff
+    '''
+    pass
+
+def noSentence():
+    '''this doesn't start with a
+    capital. so it's not considered
+    a sentence
+    '''
+    pass
+
+def emptyLine():
+    '''This is the real summary
+
+    However, it did't end with a period.
+    '''
+    pass

tests/test_autosummary.py

@@ -8,9 +8,11 @@
     :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+import sys
 
 from sphinx.ext.autosummary import mangle_signature
 
+from util import with_app, test_roots
 
 def test_mangle_signature():
     TEST = """
@@ -36,3 +38,65 @@ def test_mangle_signature():
     for inp, outp in TEST:
         res = mangle_signature(inp).strip().replace(u"\u00a0", " ")
         assert res == outp, (u"'%s' -> '%s' != '%s'" % (inp, res, outp))
+
+
+# I can't just run this directly, because I need to monkey-patch Autosummary and
+# modify the python path BEFORE creating the app... so I use
+# _do_test_get_items_summary func just as a handy way to build the app, and
+# test_get_items_summary will do the "setup", and is what is actually discovered
+# / run by nose...
+
+@with_app(confoverrides={'extensions': ['sphinx.ext.autosummary'],
+                         'autosummary_generate': True,
+                         'source_suffix': '.rst'},
+          buildername='html', srcdir=(test_roots / 'test-autosummary'))
+def _do_test_get_items_summary(app):
+    (app.srcdir / 'contents.rst').write_text(
+            '\n.. autosummary::'
+            '\n   :nosignatures:'
+            '\n   :toctree:'
+            '\n   '
+            '\n   dummy_module'
+            '\n')
+
+    app.builder.build_all()
+
+def test_get_items_summary():
+    # monkey-patch Autosummary.get_items so we can easily get access to it's
+    # results..
+    import sphinx.ext.autosummary
+    orig_get_items = sphinx.ext.autosummary.Autosummary.get_items
+
+    autosummary_items = {}
+
+    def new_get_items(self, names, *args, **kwargs):
+        results = orig_get_items(self, names, *args, **kwargs)
+        for name, result in zip(names, results):
+            autosummary_items[name] = result
+        return results
+
+    sphinx.ext.autosummary.Autosummary.get_items = new_get_items
+    try:
+        # Now, modify the python path...
+        srcdir = test_roots / 'test-autosummary'
+        sys.path.insert(0, srcdir)
+        try:
+            _do_test_get_items_summary()
+        finally:
+            if srcdir in sys.path:
+                sys.path.remove(srcdir)
+            # remove the auto-generated dummy_module.rst
+            dummy_rst = srcdir / 'dummy_module.rst'
+            if dummy_rst.isfile():
+                dummy_rst.unlink()
+    finally:
+        sphinx.ext.autosummary.Autosummary.get_items = orig_get_items
+
+    expected_values = {
+        'withSentence': 'I have a sentence which spans multiple lines.',
+        'noSentence': "this doesn't start with a",
+        'emptyLine': "This is the real summary",
+    }
+    for key, expected in expected_values.iteritems():
+        assert autosummary_items[key][2] == expected, 'Summary for %s was %r -'\
+            ' expected %r' % (key, autosummary_items[key], expected)