[stdlib-sig] pydoc enhancements

[Ron Adam]

A few weeks ago I created a patch for pydoc which removes it's dependency 
on tk by adding a navigation bar to the top of the pages served to the browser.


http://bugs.python.org/issue2001

The patch applies to python 2.6, but does not apply to 3.0 cleanly at this 
time. (Use the newest one, the older 2 patches can be deleted.)



To make these changes, the html server in pydoc was altered to be less 
independent on other parts of pydoc, ie.. more general use.  It's possible 
that this part could fit into http module.  This server serves generated 
strings instead of files.  Possibly SimpleHTTPServer should be 
SimpleHTTPFIleServer... or the py3k equivalent, http.server and 
http.fileserver?  The http file server could possibly subclass the http.server?




Back to the PyDoc enhancements...

The served html page headers has a compact navbar that includes the 
following elements.

     + The python version being used.

     + A get field that accepts most things you would type at the 
interactive prompt.  This allows you to "get" a specific items docs without 
  searching if you know the name.

     + A search field that returns the same list as the "modules 
search_term" at interactive help prompt.  (or list all modules if no 
search_term is given.)

     + An "index" link that returns the main module index page.

     + A "keywords" and "topics" link that returns the same list as typing 
keywords or topics in interactive help.  And those links work if the html 
docs are installed.

     + The "file" links on each pydoc page reads the *.py file in text mode 
and inserts the listing into an html page rather than relying on the 
browser to do the right thing with the file.  This is much much safer and 
personally I think this is a bug (poor design) that needs fixing.

     + Starting "python -g" opens up the browser directly to the module 
index page. From there you can either click on a module in the index or use 
the added navbar header to get more specific help.



All of these enhancements make moving around in the browser and looking at 
python module docs very nice and easy.  No more switching back and forth 
between a tk control window and the browser.  I think it would be nice to 
have this in python 2.6 and later.

Note: The navbar header is not added to the generated html files as they 
won't use the same interactive server.



Unfortunately, I will be starting a trip tomorrow and will be away from my 
computer for a week to two weeks.  But I wanted to get this in before the 
14th idea deadline.  I will try to work on it more and include any 
suggestions when I get back, or maybe someone else would like to finish it 
up.  I think python docs will need to be updated.  Also it needs to be 
checked to be sure it works correctly across platforms/browsers.  There is 
currently no tests for the pydoc module although there is a file to 
manually check pydoc output in the Lib/test directory that could possibly 
be used to create a test with.


Cheers,
    Ron