[Python-ideas] Improving Pydoc

[Ron Adam]

Thomas Heller wrote:
> Ron Adam schrieb:
>> 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.
> 
> Yes, I remember several cases where I had to copy code out of pydoc.py because I wanted
> to reuse it and could not because pydoc pulls in too much stuff (I care about this when
> freezing my programs with py2exe).
> Is splitting pydoc into 2 modules sufficient, or should it even be split into an own package?

That is one of the questions I have, which would be preferable.  Here's a list 
of files I have and what they do.

pyhelp.py        - Command line option parser / front end
gettext.py       - Generates text output
scanner.py       - module and search functions
_pydoc.py        - starts server and web browser
gethtml.py       - Generate html output
server.py        - html server
pager.py         - multy-platform console text pager
stringtools.py   - frequently used string formatting functions
stylesheet.css

There is still quite a bit of inter-dependence between these, but not anywhere 
near as complex as the original was. I think you will need to look at the source 
to see what is actually going on though. I'll be posting a link to it either 
today or tomorrow.


> Although I do not believe that this is on-topic for *this* list; I would prefer
> such changes to go into Python 2.6 already.

As Brett said, and Guido promoted by asking for volunteers:

On 12/18/06, Brett Cannon <brett at python.org> wrote:

 > A Python pie-in-the-sky list (python-ideas?) seems reasonable.  Let's
 > python-dev focus on maintaining the current code, python-3000 on
 > Py3K-specific work, and the ideas list to be where new ideas are vetted out
 > and congealed into a PEP to bring to either python-3000 or python-dev.


While we could hash out the exact meaning of 'pie-in-the-sky', 'new-ideas', 
'vetted out and congealed', etc...  my general impression is that things that 
aren't ready yet for python-dev or python-3000 should be here until they are 
ready.  Then of course, it could be moved to python-dev if you prefer.  I would 
like that too.

This give us a place where we can have in progress discussion of features and 
*alternatives* without disrupting python-dev or python-3000 with things that 
aren't ready.

In this case, there is still a lot more this needs before it's ready I think.  A 
PEP?  A fully (or mostly) working patch?  But maybe if others take an interest 
here, it won't be here long. ;-)

Cheers,
    Ron