DOC: Truncate docstrings of expired functions

This makes the expiration more obvious than a single line at the end, as
well as prevents doctests from raising ExpiredDeprecationErrors

Author: effigies

nibabel/deprecator.py

@@ -182,8 +182,18 @@ def deprecated_func(*args, **kwargs):
                 warnings.warn(message, warn_class, stacklevel=2)
                 return func(*args, **kwargs)
 
-            deprecated_func.__doc__ = _add_dep_doc(deprecated_func.__doc__,
-                                                   message, TESTSETUP, TESTCLEANUP)
+            keep_doc = deprecated_func.__doc__
+            setup = TESTSETUP
+            cleanup = TESTCLEANUP
+            # After expiration, remove all but the first paragraph.
+            # The details are no longer relevant, but any code will likely
+            # raise exceptions we don't need.
+            if keep_doc and until and self.is_bad_version(until):
+                lines = '\n'.join(line.rstrip() for line in keep_doc.splitlines())
+                keep_doc = lines.split('\n\n', 1)[0]
+                setup = ''
+                cleanup = ''
+            deprecated_func.__doc__ = _add_dep_doc(keep_doc, message, setup, cleanup)
             return deprecated_func
 
         return deprecator

nibabel/tests/test_deprecator.py

@@ -111,11 +111,14 @@ def test_dep_func(self):
                 'foo\n\n* deprecated from version: 1.2\n* Raises '
                 f'{ExpiredDeprecationError} as of version: 1.8\n')
         func = dec('foo', '1.2', '1.8')(func_doc_long)
-        assert (func.__doc__ ==
-                'A docstring\n   \n   foo\n   \n   * deprecated from version: 1.2\n   '
-                f'* Raises {ExpiredDeprecationError} as of version: 1.8\n   \n'
-                f'{indent(TESTSETUP, "   ", lambda x: True)}'
-                f'   Some text\n{indent(TESTCLEANUP, "   ", lambda x: True)}')
+        assert func.__doc__ == f"""\
+A docstring
+
+foo
+
+* deprecated from version: 1.2
+* Raises {ExpiredDeprecationError} as of version: 1.8
+"""
         with pytest.raises(ExpiredDeprecationError):
             func()