[issue2001] Pydoc interactive browsing enhancement

[Ron Adam]

Ron Adam <ron_adam at users.sourceforge.net> added the comment:

Thanks for the review and style edits Éric.  I think it's a much better patch with the changes and suggestions from you, Nick, and  Alexander.

I'll check my white space settings.  Thanks for noticing it.

As Nick points out, parts of the patch was written with the idea of having the text server as a separate module.  So I made the example in it runnable as a doctest, as if it was going to be a public module.  As Nick also suggests, the server example could be changed to a comment, and it could be condensed quite a bit by removing the command line doctest formatting/tutorial style and replacing it with a nice single example as it would be seen in a file.

Originally I was  hopping to get a complete rewrite into python 3.0. Then it was suggested I try for 2.6.  While doing that, I went way overboard with making it have plug in html formatters and converters. (Some people suggested they wanted that). In the end, I found that these parts in this patch, (and some additional stuff), can be used without the complete rewrite.  And these parts really help make pydoc much more usable.  Not the document generating parts.  Maybe we can move some of those parts to a pydoc_lib.py file at some point, and have an API for creating document generators rather than try to have pydoc do everything it self.

As you noticed, I used an html style that is similar to what was in the other parts of pydoc.  And yes, it's not pretty.  As Nick points out, "those things should be fixed", and I agree.  But I feel it should be a separate patch.  That will make it easier to review and keep the html code changes separate from any functional changes.  Hopefully, we can update the html so it makes good use of the style sheet at that time as well.  ie... a lot of the html code will probably be changed in the near future, so don't be too nit-picky about it right now.

Other things that I hope to add later, are to have more references in the topics and keywords be links.  That one is fairly easy. The function to do that is already in pydoc.  Add line numbers and color output to the file view page.  And eventually look into detecting and using reST to enhance both the html and text output in docstrings, topics, and keywords.

As for the imports that arn't at the top of the module, I followed the usage that was in pydoc.  It seemed to me that there was probably a conscious reason for why it done that way.

I can't find anything I disagree with. 

   Ron

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue2001>
_______________________________________