diff --git a/CHANGES b/CHANGES index 2f4da53a1..8c313bd69 100644 --- a/CHANGES +++ b/CHANGES @@ -118,6 +118,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 ------------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 27cd21c4d..ed4771c1b 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/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() diff --git a/tests/roots/test-autosummary/conf.py b/tests/roots/test-autosummary/conf.py new file mode 100644 index 000000000..dc54762e9 --- /dev/null +++ b/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 diff --git a/tests/roots/test-autosummary/contents.rst b/tests/roots/test-autosummary/contents.rst new file mode 100644 index 000000000..32390a32e --- /dev/null +++ b/tests/roots/test-autosummary/contents.rst @@ -0,0 +1,6 @@ + +.. autosummary:: + :nosignatures: + :toctree: + + dummy_module diff --git a/tests/roots/test-autosummary/dummy_module.py b/tests/roots/test-autosummary/dummy_module.py new file mode 100644 index 000000000..382e19db3 --- /dev/null +++ b/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 diff --git a/tests/test_autosummary.py b/tests/test_autosummary.py index cb6a6b745..caa018c54 100644 --- a/tests/test_autosummary.py +++ b/tests/test_autosummary.py @@ -8,9 +8,11 @@ :copyright: Copyright 2007-2013 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)