[Python-Dev] Pydoc Improvements / Rewrite

[Ron Adam]

I started to discuss this on the new python-ideas list because I thought it may 
need a bit more completion before bringing it here.  But It was suggested that 
it really does belong here as it is something that would be nice to have in 
python 2.6.  So I'm reposting the introduction here.

The still very rough source files can be downloaded from:

        http://ronadam.com/dl/_pydoc.zip

There is still much to do, but I think having some experienced feed back on 
where it should go is important.

Cheers,
    Ron Adam

ps.. Please disregard the website for now, it's purpose was to share with family 
and friends, although I will probably share the python source to the ledger 
program there and other python toys and experiments (for fun) in the near future.



[Introduction From python-ideas list]

Improving pydoc has been suggested before by me and others.  I've been working
on a version that is probably 80% done and would like to get feed back at this
point to determine if I'm approaching this in the best way.

Basically pydoc.py consists of over 2,000 lines of python code and is not well
organized inside which means (my thoughts) it will pretty much stay the way it
is and not be as useful as it could be.

Currently pydoc.py has the following uses.

      * It is imported and used as pythons console help function.
      * It can be used to generate help text files.
      * It can open a tkinter search index and from that launch a web server and
a browser to veiw a html help page.
      * It can be used to generate static html help files.


It looks (to me) like splitting it into two modules would be good.  One module
for just the text help and introspection functions, and the other for the html
server and html output stuff.

[It was suggested on python-ideas that making it a package may be good.]


1. pyhelp.py - Pythons help function from inside the console, and running it
directly would open an interactive text help session.

2. _pydoc.py - Python html help browser.  This starts an html server and opens a
web page with a modules/package index.  The html page headers would contain the
current Python version info and the following inputs fields.

      * get field - directly bring up help on an object/module/or package.
      * Search field - returns a search results index.
      * Modules button - modules index page
      * Keywords button - keywords index page
      * Help button - pydoc Help instructions, version, and credits info.

Note: The leading underscore "_pydoc.py" is to keep it from clashing with the
current pydoc version.  It probably should be something else.


An additional feature is clicking on a filename opens up a numbered source
listing. Which is nice for source code browsing and for referencing specific
lines of code in python list discussions.  ;-)

The colors, fonts and general appearance can be changed by editing the style
sheet.  The output is readable as plain (outline form) text if the style sheet
is ignored by the browser.

_pydoc.py imports pyhelp and uses it to do the introspection work and extends
classes in pyhelp to produce html output.  I've tried to make pyhelp.py useful
in a general way so that it can more easily be used as a base that other output
formats can be built from. That's something that can't be done presently.

These improvements to pydoc mean you can browse pythons library dynamically
without ever leaving the web browser. Currently you switch back and forth
between the browser and a tkinter index window.  Something I found to be
annoying enough to discourage me from using pydoc.


The version I'm working on is split up into eight python files, each addressing
a particular function of pydoc. That was to help me organize things better.
These will be recombined into fewer files.  Some parts of it could be moved to
other modules if they seem more generally useful.  For example, the console text
pager could be used in many other console applications.

Things that still need to be done are adding the object resolution order output
back in.  And adding inter-page html links back in.  And a few other things I
just haven't gotten to yet.  I got a bit burned out on this project a while
back, and then moved to a new house.. etc.. etc..  But I'm starting to have more
time, and with the current discussion s turning on to refining pythons library
this seems like it would be a useful tool in that effort.

Any comments on this general approach?  Any suggestions, questions, or comments?

I'll post a link to the zipped files in the next day or two and announce it
here. I need to look into a glitch on my computer first that's probably a
windows path/name problem. I don't think it's anything that needs to be fixed in
the files but I want to be sure.

Cheers,
     Ron Adam