[Python-Dev] Python Doc problems

[Ron Adam]

Josiah Carlson wrote:
> "BJörn Lindqvist" <bjourne at gmail.com> wrote:
>>> If there are "rampant criticisms" of the Python docs, then those that
>>> are complaining should take specific examples of their complaints to the
>>> sourceforge bug tracker and submit documentation patches for the
>>> relevant sections.  And personally, I've not noticed that criticisms of
>>> the Python docs are "rampant", but maybe there is some "I hate Python
>>> docs" newsgroup or mailing list that I'm not subscribed to.
>> Meh! The number one complaint IS that you have to take your complaints
>> to the sourceforge bug tracker and submit documentation patches. For
>> documentation changes, that is way to much overhead for to little
>> gain. But thankfully I think there are people working on fixing those
>> problems which is very nice.
> 
> Are you telling me that people want to be able to complain into the
> ether and get their complaints heard?  I hope not, because that would be
> insane.  Also, "doc patches" are basically "the function foo() should be
> documented as ...", users don't need to know or learn TeX.  Should there
> be an easier method of submitting doc fixes, etc.? Sure. But people are
> still going to need to actually *report* the fixes they want, which they
> aren't doing in *any* form now.

Maybe a doc fix day (similar to the bug fix day) would be good.  That way we can 
report a lot of minor doc fix's at once and then they can be fixed in batches.

For example of things I think may be thought of as too trivial to report but 
effect readability and ease of use with pythons help() function ...

A *lot* of doc strings have lines that wrap when they are displayed by pythons 
help() in a standard 80 column console window.

There are also two (maybe more) modules that have single backslash characters in 
their doc strings that get ate when viewed by pydoc.

     cookielib.py   -  has single '\'s in a diagram.

     SimpleXMLRPCServer.py  - line 31... code example with line continuation.

I wonder if double \ should also be allowed as line continuations so that 
doctests would look and work ok in doc strings when viewed by pythons help()?


Anyway if someone wants to search for other things of that type they can play 
around with the hacked together tool included below.  Setting it low enough so 
that indented methods don't wrap with the help() function brings up several 
thousand instances. I'm hoping most of those are duplicated/inherited doc strings.

Many of those are documented format lines with the form ...

    name( longs_list_of_arguments ... ) -> long_list_of_return_types ...


Rather than fix all of those, I'm changing the version of pydoc I've been 
rewriting to wordwrap lines.  Although that's not the prettiest solution, it's 
better than breaking the indented margin.


     Have fun...  ;-)

Ron


"""
     Find doc string lines are not longer than n characters.

     Dedenting the doc strings before testing may give more
     meaningful results.
"""
import sys
import os
import inspect
import types

class NullType(object):
     """ A simple Null object to use when None is a valid
     argument, or when redirecting print to Null. """
     def write(self, *args):
         pass
     def __repr__(self):
         return "Null"
Null = NullType()


check = 'CHECKING__________'
checkerr = 'ERROR CHECKING____'
err_obj = []
err_num = 0
stdout = sys.stdout
stderr = sys.stderr
seporator = '--------------------------------------------------------'
linelength = 100

def main():
     sys_path = sys.path
     # remove invalid dirs
     for f in sys_path[:]:
         try:
             os.listdir(f)
         except:
             sys_path.remove(f)
     #checkmodule('__builtin__')
     for mod in sys.builtin_module_names:
         checkmodule(mod)
     for dir_ in sys.path:
         for f in os.listdir(dir_):
             if f.endswith('.py') or f.endswith('.pyw') or f.endswith('.pyd'):
                 try:
                     checkmodule(f.partition('.')[0])
                 except Exception:
                     print seporator
                     print checkerr, f, err_obj
                     print '   %s: %s' % (sys.exc_type.__name__, sys.exc_value)
     print seporator

def checkmodule(modname):
     global err_obj
     err_obj = [modname]
     # Silent text printed on import.
     sys.stdout = sys.stderr = Null
     try:
         module = __import__(modname)
     finally:
         sys.stdout = stdout
         sys.stderr = stderr
     try:
         checkobj(module)               # module doc string
         for o1 in dir(module):
             obj1 = getattr(module, o1)
             err_obj = [modname, o1]
             checkobj(obj1)             # class and function doc strings
             for o2 in dir(obj1):
                 obj2 = getattr(obj1, o2)
                 err_obj = [modname, o1, o2]
                 checkobj(obj2)              # method doc strings
     finally:
         del module

def checkobj(obj):
     global err_num
     if not hasattr(obj, '__doc__'):
         return
     doc = str(obj.__doc__)
     err_obj.append('__doc__')
     lines = doc.split('\n')
     longlines = [x for x in lines if len(x) > linelength]
     if longlines:
         err_num += 1
         print seporator
         print '#%i: %s' % (err_num, '.'.join([str(x) for x in err_obj]))
         print
         for x in longlines:
             print len(x), repr(x.strip())

if __name__ == '__main__':
     main()