diff -r 528234542ff0 Doc/library/inspect.rst --- a/Doc/library/inspect.rst Mon Apr 14 16:49:07 2014 -0400 +++ b/Doc/library/inspect.rst Mon Apr 14 17:52:47 2014 -0400 @@ -349,6 +349,12 @@ Python source file (if the object is a module). +.. function:: splitdoc(object) + + Return a tuple where the first element is the synopsis of the function and the second + element is just the rest of the documentation. + + .. function:: getfile(object) Return the name of the (text or binary) file in which an object was defined. diff -r 528234542ff0 Lib/inspect.py --- a/Lib/inspect.py Mon Apr 14 16:49:07 2014 -0400 +++ b/Lib/inspect.py Mon Apr 14 17:52:47 2014 -0400 @@ -13,6 +13,7 @@ getfile(), getsourcefile(), getsource() - find an object's source code getdoc(), getcomments() - get documentation on an object + splitdoc() - Split a doc string into a synopsis line (if any) and the rest getmodule() - determine the module that an object came from getclasstree() - arrange classes so as to represent their hierarchy @@ -482,6 +483,18 @@ return None return cleandoc(doc) +def splitdoc(object): + """Split a doc string into a synopsis line (if any) and the rest.""" + result = getdoc(object) or getcomments(object) + doc = result and re.sub('^ *\n', '', result.rstrip()) or '' + + lines = doc.strip().split('\n') + if len(lines) == 1: + return lines[0], '' + elif len(lines) >= 2 and not lines[1].rstrip(): + return lines[0], '\n'.join(lines[2:]) + return '', '\n'.join(lines) + def cleandoc(doc): """Clean up indentation from docstrings. diff -r 528234542ff0 Lib/pydoc.py --- a/Lib/pydoc.py Mon Apr 14 16:49:07 2014 -0400 +++ b/Lib/pydoc.py Mon Apr 14 17:52:47 2014 -0400 @@ -88,15 +88,6 @@ result = inspect.getdoc(object) or inspect.getcomments(object) return result and re.sub('^ *\n', '', result.rstrip()) or '' -def splitdoc(doc): - """Split a doc string into a synopsis line (if any) and the rest.""" - lines = doc.strip().split('\n') - if len(lines) == 1: - return lines[0], '' - elif len(lines) >= 2 and not lines[1].rstrip(): - return lines[0], '\n'.join(lines[2:]) - return '', '\n'.join(lines) - def classname(object, modname): """Get a class name and qualify it with a module name if necessary.""" name = object.__name__ @@ -1083,7 +1074,7 @@ def docmodule(self, object, name=None, mod=None): """Produce text documentation for a given module object.""" name = object.__name__ # ignore the passed-in name - synop, desc = splitdoc(getdoc(object)) + synop, desc = inspect.splitdoc(object) result = self.section('NAME', name + (synop and ' - ' + synop)) all = getattr(object, '__all__', None) docloc = self.getdocloc(object) diff -r 528234542ff0 Lib/test/test_inspect.py --- a/Lib/test/test_inspect.py Mon Apr 14 16:49:07 2014 -0400 +++ b/Lib/test/test_inspect.py Mon Apr 14 17:52:47 2014 -0400 @@ -280,6 +280,11 @@ self.assertEqual(inspect.getdoc(git.abuse), 'Another\n\ndocstring\n\ncontaining\n\ntabs') + def test_splitdoc(self): + self.assertEqual(inspect.splitdoc(mod), ('A module docstring.', '')) + self.assertEqual(inspect.splitdoc(mod.StupidGit), + ('A longer,', 'indented\n\ndocstring.')) + def test_cleandoc(self): self.assertEqual(inspect.cleandoc('An\n indented\n docstring.'), 'An\nindented\ndocstring.')