refactor: Add extract_summary() for easily testing

sphinx/ext/autosummary/__init__.py

@@ -340,27 +340,7 @@ class Autosummary(Directive):
             # -- Grab the summary
 
             documenter.add_content(None)
-            doc = self.result.data
-
-            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()
-            elif doc:
-                summary = doc[0].strip()
-            else:
-                summary = ''
+            summary = extract_summary(self.result.data[:])
 
             items.append((display_name, sig, summary, real_name))
 
@@ -467,6 +447,34 @@ def mangle_signature(sig, max_chars=30):
     return u"(%s)" % sig
 
 
+def extract_summary(doc):
+    # type: (List[unicode]) -> unicode
+    """Extract summary from docstring."""
+
+    # Skip a blank lines at the top
+    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()
+    elif doc:
+        summary = doc[0].strip()
+    else:
+        summary = ''
+
+    return summary
+
+
 def limited_join(sep, items, max_chars=30, overflow_marker="..."):
     # type: (unicode, List[unicode], int, unicode) -> unicode
     """Join a number of strings to one, limiting the length to *max_chars*.

tests/test_ext_autosummary.py

@@ -9,14 +9,12 @@
     :license: BSD, see LICENSE for details.
 """
 
+import pytest
 from six import iteritems, StringIO
 
-from sphinx.ext.autosummary import mangle_signature, import_by_name
-
+from sphinx.ext.autosummary import mangle_signature, import_by_name, extract_summary
 from sphinx.testing.util import etree_parse
 
-import pytest
-
 html_warnfile = StringIO()
 
 
@@ -57,6 +55,14 @@ def test_mangle_signature():
         assert res == outp, (u"'%s' -> '%s' != '%s'" % (inp, res, outp))
 
 
+def test_extract_summary():
+    doc = ['',
+           'This is a first sentence. And second one.',
+           '',
+           'Second block is here']
+    assert extract_summary(doc) == 'This is a first sentence.'
+
+
 @pytest.mark.sphinx('dummy', **default_kw)
 def test_get_items_summary(make_app, app_params):
     import sphinx.ext.autosummary