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. 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
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? 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. Thomas BTW: It seems this list is not yet available on gmane. Is this correct?
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@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
On 12/22/06, Ron Adam <rrr@ronadam.com> wrote:
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.
I do like your idea of splitting the screen pager and the HTML aspect, Ron. And yes, pydoc needs a cleanup.
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@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. ;-)
I don't view code cleanup as something for this list. I view stuff like "I want to hash out an idea on abstract base classes" and the ilk. Code reorganization, etc. that are more software engineering and completely new idea should still go to python-dev or python-3000. Basically stuff where people might throw a fit over the idea should probably come here until it is a solid idea. =) So I agree with Thomas; this should go to python-dev. -Brett
Brett Cannon wrote:
I do like your idea of splitting the screen pager and the HTML aspect, Ron. And yes, pydoc needs a cleanup.
The screen pager is not dependent on any other parts. So it would make an ideal module on it's own, or it could be a part of console io device object. The html server is very much cleaned up. It is a nice example of how to write a html server and can stand on it's own as an example module I think.
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. ;-)
I don't view code cleanup as something for this list. I view stuff like "I want to hash out an idea on abstract base classes" and the ilk. Code reorganization, etc. that are more software engineering and completely new idea should still go to python-dev or python-3000. Basically stuff where people might throw a fit over the idea should probably come here until it is a solid idea. =)
So I agree with Thomas; this should go to python-dev.
It's still pretty raw in some places, but maybe that's ok. I'll post and introduction and the link in python-dev, I also think I uncovered a bug in the browser module, so maybe they can look at that too. It will be interesting to see what will be discussed here, I have some farther out "fit-throwing" ideas as well. ;-) Cheers, Ron
participants (3)
-
Brett Cannon -
Ron Adam -
Thomas Heller