Index: trunk/Lib/pydoc.py
===================================================================
--- trunk/Lib/pydoc.py	(revision 61445)
+++ trunk/Lib/pydoc.py	(working copy)
@@ -308,6 +308,27 @@
         except AttributeError: return None
     return module
 
+def getDocAncestor(methodObject):
+    '''Return (docString, class) for the first class in the method 
+    resolution order with a doc string for a method with the same name
+    as methodObject's, or ('', <methodObject's class>) if none is found.
+    '''
+    name = methodObject.__name__
+    imclass = methodObject.im_class
+    doc = getdoc(methodObject.im_func) 
+    if not doc:  
+        mro = inspect.getmro(imclass)[1:]
+        for ancestor in mro:
+            if name in ancestor.__dict__:
+                attr = getattr(ancestor, name)
+                if inspect.ismethod(attr): 
+                    doc = getdoc(attr)
+                    if doc:
+                        return (doc, ancestor)
+                else: # no docs to substitute if namesake not a method
+                    break
+    return (doc, imclass)
+
 # ---------------------------------------------------- formatter base class
 
 class Doc:
@@ -594,6 +615,7 @@
             if sys.platform == 'win32':
                 import nturl2path
                 url = nturl2path.pathname2url(path)
+                #url = '///' + path  #.replace('\\','/')  # \ or / in firefox path OK
             filelink = '<a href="file:%s">%s</a>' % (url, path)
         except TypeError:
             filelink = '(built-in)'
@@ -848,6 +870,7 @@
         anchor = (cl and cl.__name__ or '') + '-' + name
         note = ''
         skipdocs = 0
+        doc = ''  
         if inspect.ismethod(object):
             imclass = object.im_class
             if cl:
@@ -859,8 +882,13 @@
                         object.im_self.__class__, mod)
                 else:
                     note = ' unbound %s method' % self.classlink(imclass,mod)
+            
+            (doc, ancestor) = getDocAncestor(object)
+            if ancestor is not imclass:
+                note +=', docs of inherited %s' % self.classlink(ancestor, mod)
+                                
             object = object.im_func
-
+            
         if name == realname:
             title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
         else:
@@ -890,7 +918,7 @@
             return '<dl><dt>%s</dt></dl>\n' % decl
         else:
             doc = self.markup(
-                getdoc(object), self.preformat, funcs, classes, methods)
+                doc or getdoc(object), self.preformat, funcs, classes, methods)
             doc = doc and '<dd><tt>%s</tt></dd>' % doc
             return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
 
@@ -933,7 +961,6 @@
         return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
 
 # -------------------------------------------- text documentation generator
-
 class TextRepr(Repr):
     """Class for safely making a text representation of a Python object."""
     def __init__(self):
@@ -1230,6 +1257,7 @@
         name = name or realname
         note = ''
         skipdocs = 0
+        doc = ''
         if inspect.ismethod(object):
             imclass = object.im_class
             if cl:
@@ -1241,8 +1269,13 @@
                         object.im_self.__class__, mod)
                 else:
                     note = ' unbound %s method' % classname(imclass,mod)
+            
+            (doc, ancestor) = getDocAncestor(object)
+            if ancestor is not imclass:
+                note +=', docs of inherited %s' % classname(ancestor, mod)
+                
             object = object.im_func
-
+            
         if name == realname:
             title = self.bold(realname)
         else:
@@ -1264,7 +1297,7 @@
         if skipdocs:
             return decl + '\n'
         else:
-            doc = getdoc(object) or ''
+            doc = doc or getdoc(object) or '' 
             return decl + '\n' + (doc and rstrip(self.indent(doc)) + '\n')
 
     def _docdescriptor(self, name, value, mod):
Index: trunk/Lib/test/test_pydoc.html
===================================================================
--- trunk/Lib/test/test_pydoc.html	(revision 0)
+++ trunk/Lib/test/test_pydoc.html	(revision 0)
@@ -0,0 +1,159 @@
+
+<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html><head><title>Python: module test.test_pydoc_sample</title>
+</head><body bgcolor="#f0f0f8">
+
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
+<tr bgcolor="#7799ee">
+<td valign=bottom>&nbsp;<br>
+<font color="#ffffff" face="helvetica, arial">&nbsp;<br><big><big><strong><a href="test.html"><font color="#ffffff">test</font></a>.test_pydoc_sample</strong></big></big></font></td
+><td align=right valign=bottom
+><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:///C|/anh/python/pydev/trunk/lib/test/test_pydoc_sample.py">c:\anh\python\pydev\trunk\lib\test\test_pydoc_sample.py</a></font></td></tr></table>
+    <p><tt>Sample&nbsp;module&nbsp;used&nbsp;by&nbsp;test_pydoc_inheritance.py<br>
+Docs&nbsp;for&nbsp;this&nbsp;module&nbsp;are&nbsp;generated,&nbsp;testing<br>
+'inherited'&nbsp;doc&nbsp;strings&nbsp;for&nbsp;pydoc.<br>
+Function&nbsp;names&nbsp;encode&nbsp;for&nbsp;the&nbsp;places&nbsp;where&nbsp;there&nbsp;are<br>
+docs&nbsp;in&nbsp;the&nbsp;source&nbsp;code&nbsp;in&nbsp;the&nbsp;subclassing&nbsp;sequence&nbsp;<a href="#A">A</a>,&nbsp;<a href="#B">B</a>,&nbsp;<a href="#C">C</a>.<br>
+<a href="#A">A</a>,&nbsp;<a href="#B">B</a>&nbsp;or&nbsp;<a href="#C">C</a>&nbsp;indicate&nbsp;classes&nbsp;where&nbsp;the&nbsp;function&nbsp;with&nbsp;this&nbsp;name&nbsp;has&nbsp;docs.<br>
+a,&nbsp;b&nbsp;or&nbsp;c&nbsp;indicate&nbsp;classes&nbsp;with&nbsp;a&nbsp;function&nbsp;of&nbsp;this&nbsp;name&nbsp;but&nbsp;no&nbsp;docs.</tt></p>
+<p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ee77aa">
+<td colspan=3 valign=bottom>&nbsp;<br>
+<font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
+    
+<tr><td bgcolor="#ee77aa"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
+<td width="100%"><dl>
+<dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a>
+</font></dt><dd>
+<dl>
+<dt><font face="helvetica, arial"><a href="test.test_pydoc_sample.html#A">A</a>
+</font></dt><dd>
+<dl>
+<dt><font face="helvetica, arial"><a href="test.test_pydoc_sample.html#B">B</a>
+</font></dt><dd>
+<dl>
+<dt><font face="helvetica, arial"><a href="test.test_pydoc_sample.html#C">C</a>
+</font></dt></dl>
+</dd>
+</dl>
+</dd>
+</dl>
+</dd>
+</dl>
+ <p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ffc8d8">
+<td colspan=3 valign=bottom>&nbsp;<br>
+<font color="#000000" face="helvetica, arial"><a name="A">class <strong>A</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
+    
+<tr><td bgcolor="#ffc8d8"><tt>&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
+<td width="100%">Methods defined here:<br>
+<dl><dt><a name="A-fABc"><strong>fABc</strong></a>(self, x)</dt><dd><tt>This&nbsp;is&nbsp;fABc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="A-fAbc"><strong>fAbc</strong></a>(self, x)</dt><dd><tt>This&nbsp;fAbc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="A-fAc"><strong>fAc</strong></a>(self, x)</dt><dd><tt>This&nbsp;is&nbsp;fAc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="A-faBc"><strong>faBc</strong></a>(self)</dt></dl>
+
+<dl><dt><a name="A-fabC"><strong>fabC</strong></a>(self)</dt></dl>
+
+<dl><dt><a name="A-fabc"><strong>fabc</strong></a>(self)</dt></dl>
+
+<hr>
+Data descriptors defined here:<br>
+<dl><dt><strong>__dict__</strong></dt>
+<dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+<dl><dt><strong>__weakref__</strong></dt>
+<dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+</td></tr></table> <p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ffc8d8">
+<td colspan=3 valign=bottom>&nbsp;<br>
+<font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(<a href="test.test_pydoc_sample.html#A">A</a>)</font></td></tr>
+    
+<tr><td bgcolor="#ffc8d8"><tt>&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
+<td width="100%"><dl><dt>Method resolution order:</dt>
+<dd><a href="test.test_pydoc_sample.html#B">B</a></dd>
+<dd><a href="test.test_pydoc_sample.html#A">A</a></dd>
+<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
+</dl>
+<hr>
+Methods defined here:<br>
+<dl><dt><a name="B-fABc"><strong>fABc</strong></a>(self, x)</dt><dd><tt>This&nbsp;is&nbsp;fABc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="B-fAbc"><strong>fAbc</strong></a>(self, x)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#A">A</a></font></font></dt><dd><tt>This&nbsp;fAbc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="B-fBc"><strong>fBc</strong></a>(self)</dt><dd><tt>This&nbsp;is&nbsp;fBc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="B-faBc"><strong>faBc</strong></a>(self)</dt><dd><tt>This&nbsp;is&nbsp;faBc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="B-fabC"><strong>fabC</strong></a>(self)</dt></dl>
+
+<dl><dt><a name="B-fabc"><strong>fabc</strong></a>(self)</dt></dl>
+
+<dl><dt><a name="B-fbC"><strong>fbC</strong></a>(self)</dt></dl>
+
+<hr>
+Methods inherited from <a href="test.test_pydoc_sample.html#A">A</a>:<br>
+<dl><dt><a name="B-fAc"><strong>fAc</strong></a>(self, x)</dt><dd><tt>This&nbsp;is&nbsp;fAc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<hr>
+Data descriptors inherited from <a href="test.test_pydoc_sample.html#A">A</a>:<br>
+<dl><dt><strong>__dict__</strong></dt>
+<dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+<dl><dt><strong>__weakref__</strong></dt>
+<dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+</td></tr></table> <p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ffc8d8">
+<td colspan=3 valign=bottom>&nbsp;<br>
+<font color="#000000" face="helvetica, arial"><a name="C">class <strong>C</strong></a>(<a href="test.test_pydoc_sample.html#B">B</a>)</font></td></tr>
+    
+<tr><td bgcolor="#ffc8d8"><tt>&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
+<td width="100%"><dl><dt>Method resolution order:</dt>
+<dd><a href="test.test_pydoc_sample.html#C">C</a></dd>
+<dd><a href="test.test_pydoc_sample.html#B">B</a></dd>
+<dd><a href="test.test_pydoc_sample.html#A">A</a></dd>
+<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
+</dl>
+<hr>
+Methods defined here:<br>
+<dl><dt><a name="C-fABc"><strong>fABc</strong></a>(self, x)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#B">B</a></font></font></dt><dd><tt>This&nbsp;is&nbsp;fABc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-fAbc"><strong>fAbc</strong></a>(self, x)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#A">A</a></font></font></dt><dd><tt>This&nbsp;fAbc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-fAc"><strong>fAc</strong></a>(self, x)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#A">A</a></font></font></dt><dd><tt>This&nbsp;is&nbsp;fAc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#A">A</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-fBc"><strong>fBc</strong></a>(self)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#B">B</a></font></font></dt><dd><tt>This&nbsp;is&nbsp;fBc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-faBc"><strong>faBc</strong></a>(self)<font color="#909090"><font face="helvetica, arial">, docs of inherited <a href="test.test_pydoc_sample.html#B">B</a></font></font></dt><dd><tt>This&nbsp;is&nbsp;faBc's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#B">B</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-fabC"><strong>fabC</strong></a>(self)</dt><dd><tt>This&nbsp;is&nbsp;fabC's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#C">C</a>.</tt></dd></dl>
+
+<dl><dt><a name="C-fabc"><strong>fabc</strong></a>(self)</dt></dl>
+
+<dl><dt><a name="C-fbC"><strong>fbC</strong></a>(self)</dt><dd><tt>This&nbsp;is&nbsp;fbC's&nbsp;doc&nbsp;string&nbsp;in&nbsp;<a href="#C">C</a>.</tt></dd></dl>
+
+<hr>
+Data descriptors inherited from <a href="test.test_pydoc_sample.html#A">A</a>:<br>
+<dl><dt><strong>__dict__</strong></dt>
+<dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+<dl><dt><strong>__weakref__</strong></dt>
+<dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
+</dl>
+</td></tr></table></td></tr></table><p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#55aa55">
+<td colspan=3 valign=bottom>&nbsp;<br>
+<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
+    
+<tr><td bgcolor="#55aa55"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
+<td width="100%"><strong>__package__</strong> = None</td></tr></table>
+</body></html>
\ No newline at end of file
Index: trunk/Lib/test/test_pydoc_sample.py
===================================================================
--- trunk/Lib/test/test_pydoc_sample.py	(revision 0)
+++ trunk/Lib/test/test_pydoc_sample.py	(revision 0)
@@ -0,0 +1,56 @@
+'''Sample module used by test_pydoc_inheritance.py
+Docs for this module are generated, testing
+'inherited' doc strings for pydoc.
+Function names encode for the places where there are
+docs in the source code in the subclassing sequence A, B, C.
+A, B or C indicate classes where the function with this name has docs.
+a, b or c indicate classes with a function of this name but no docs.
+'''
+
+class A(object):
+    def fAbc(self, x):
+        '''This fAbc's doc string in A.'''
+    def fABc(self, x):
+        '''This is fABc's doc string in A.'''
+    def fAc(self, x):
+        '''This is fAc's doc string in A.'''
+    def fabC(self):
+        pass
+    def faBc(self):
+        pass
+    def fabc(self):
+        pass
+
+class B(A):
+    def fAbc(self, x):
+        pass
+    def fABc(self, x):
+        '''This is fABc's doc string in B.'''
+    def fabC(self):
+        pass
+    def faBc(self):
+        '''This is faBc's doc string in B.'''
+    def fBc(self):
+        '''This is fBc's doc string in B.'''
+    def fbC(self):
+        pass
+    def fabc(self):
+        pass
+    
+class C(B):
+    def fAbc(self, x):
+        pass
+    def fABc(self, x):
+        pass
+    def fabC(self):
+        '''This is fabC's doc string in C.'''
+    def faBc(self):
+        pass
+    def fAc(self, x):
+        pass
+    def fBc(self):
+        pass
+    def fbC(self):
+        '''This is fbC's doc string in C.'''
+    def fabc(self):
+        pass
Index: trunk/Lib/test/test_pydoc.txt
===================================================================
--- trunk/Lib/test/test_pydoc.txt	(revision 0)
+++ trunk/Lib/test/test_pydoc.txt	(revision 0)
@@ -0,0 +1,133 @@
+NNAAMMEE
+    test.test_pydoc_sample
+
+FFIILLEE
+    c:\anh\python\pydev\trunk\lib\test\test_pydoc_sample.py
+
+DDEESSCCRRIIPPTTIIOONN
+    Sample module used by test_pydoc_inheritance.py
+    Docs for this module are generated, testing
+    'inherited' doc strings for pydoc.
+    Function names encode for the places where there are
+    docs in the source code in the subclassing sequence A, B, C.
+    A, B or C indicate classes where the function with this name has docs.
+    a, b or c indicate classes with a function of this name but no docs.
+
+CCLLAASSSSEESS
+    __builtin__.object
+        A
+            B
+                C
+    
+    class AA(__builtin__.object)
+     |  Methods defined here:
+     |  
+     |  ffAABBcc(self, x)
+     |      This is fABc's doc string in A.
+     |  
+     |  ffAAbbcc(self, x)
+     |      This fAbc's doc string in A.
+     |  
+     |  ffAAcc(self, x)
+     |      This is fAc's doc string in A.
+     |  
+     |  ffaaBBcc(self)
+     |  
+     |  ffaabbCC(self)
+     |  
+     |  ffaabbcc(self)
+     |  
+     |  ----------------------------------------------------------------------
+     |  Data descriptors defined here:
+     |  
+     |  ____ddiicctt____
+     |      dictionary for instance variables (if defined)
+     |  
+     |  ____wweeaakkrreeff____
+     |      list of weak references to the object (if defined)
+    
+    class BB(A)
+     |  Method resolution order:
+     |      B
+     |      A
+     |      __builtin__.object
+     |  
+     |  Methods defined here:
+     |  
+     |  ffAABBcc(self, x)
+     |      This is fABc's doc string in B.
+     |  
+     |  ffAAbbcc(self, x), docs of inherited A
+     |      This fAbc's doc string in A.
+     |  
+     |  ffBBcc(self)
+     |      This is fBc's doc string in B.
+     |  
+     |  ffaaBBcc(self)
+     |      This is faBc's doc string in B.
+     |  
+     |  ffaabbCC(self)
+     |  
+     |  ffaabbcc(self)
+     |  
+     |  ffbbCC(self)
+     |  
+     |  ----------------------------------------------------------------------
+     |  Methods inherited from A:
+     |  
+     |  ffAAcc(self, x)
+     |      This is fAc's doc string in A.
+     |  
+     |  ----------------------------------------------------------------------
+     |  Data descriptors inherited from A:
+     |  
+     |  ____ddiicctt____
+     |      dictionary for instance variables (if defined)
+     |  
+     |  ____wweeaakkrreeff____
+     |      list of weak references to the object (if defined)
+    
+    class CC(B)
+     |  Method resolution order:
+     |      C
+     |      B
+     |      A
+     |      __builtin__.object
+     |  
+     |  Methods defined here:
+     |  
+     |  ffAABBcc(self, x), docs of inherited B
+     |      This is fABc's doc string in B.
+     |  
+     |  ffAAbbcc(self, x), docs of inherited A
+     |      This fAbc's doc string in A.
+     |  
+     |  ffAAcc(self, x), docs of inherited A
+     |      This is fAc's doc string in A.
+     |  
+     |  ffBBcc(self), docs of inherited B
+     |      This is fBc's doc string in B.
+     |  
+     |  ffaaBBcc(self), docs of inherited B
+     |      This is faBc's doc string in B.
+     |  
+     |  ffaabbCC(self)
+     |      This is fabC's doc string in C.
+     |  
+     |  ffaabbcc(self)
+     |  
+     |  ffbbCC(self)
+     |      This is fbC's doc string in C.
+     |  
+     |  ----------------------------------------------------------------------
+     |  Data descriptors inherited from A:
+     |  
+     |  ____ddiicctt____
+     |      dictionary for instance variables (if defined)
+     |  
+     |  ____wweeaakkrreeff____
+     |      list of weak references to the object (if defined)
+
+DDAATTAA
+    ____ppaacckkaaggee____ = None
+
Index: trunk/Lib/test/test_pydoc_inheritance.py
===================================================================
--- trunk/Lib/test/test_pydoc_inheritance.py	(revision 0)
+++ trunk/Lib/test/test_pydoc_inheritance.py	(revision 0)
@@ -0,0 +1,70 @@
+'''Test the 'inheritance' of method docs in pydoc
+by comparing the text for a sample module to
+the text previously generated and checked, and saved
+in files test_pydoc.txt and test_pydoc.html.
+The initial part of the documentation through the 
+local file name is stripped before comparison.
+
+After intentional changes to the pydoc format,
+run the regenerateData() function and manually
+check the new versions of the files generated.'''
+
+import pydoc, os.path
+from test import test_pydoc_sample
+
+DATAFILEBASE = 'test_pydoc'
+TEXT = 'txt'
+HTML = 'html'
+
+def getDataFileName(extension):
+    'Return the data file name.'
+    basedir = os.path.split(test_pydoc_sample.__file__)[0]
+    return os.path.join(basedir, DATAFILEBASE + '.' + extension)
+
+def generateDocs(extension):
+    '''Generate and return sample doc string with current pydoc.'''
+    if extension == TEXT:
+        return pydoc.text.docmodule(test_pydoc_sample)
+    return pydoc.html.page(pydoc.describe(test_pydoc_sample), 
+                           pydoc.html.document(test_pydoc_sample))
+
+def strToFile(s, filename):
+    outf = open(filename, 'w')
+    outf.write(s)
+    outf.close()
+
+def fileToStr(filename):
+    'Return file contents string.'
+    inf = open(filename)
+    s = inf.read()
+    inf.close()
+    return s
+
+def regenerateData():
+    '''Recreate pydoc 'inheritance' reference data.
+    Use after the pydoc output format is intentionally changed.'''
+    for extension in [TEXT, HTML]:
+        strToFile(generateDocs(extension), getDataFileName(extension))
+
+def readReferenceDocs(extension):
+    'Read and return the file contents.'
+    return fileToStr(getDataFileName(extension))
+
+def stripTo(s, target):
+    '''Return the part of s from target onward.'''
+    return s[s.index(target) : ]
+
+def main():
+    '''Compare text and html pydoc 'inheritance' output 
+    to reference data.  The initial part of the text is 
+    removed before comparison.  This eliminates the local 
+    file reference at the beginning of the text.'''
+    for extension, marker in [(TEXT, pydoc.text.bold('DESCRIPTION')), 
+                              (HTML, '</table>')]:
+        newData = stripTo(generateDocs(extension), marker)
+        refData = stripTo(readReferenceDocs(extension), marker)
+        assert newData == refData
+        print "pydoc 'inheritance'", extension, 'verson OK'
+
+if __name__ == '__main__':
+    main()
