[Python-Dev] Pydoc Improvements / Rewrite

[Ron Adam]

Laurent Gautier wrote:
 > Ron,
 >
 > Thanks for your detailed answer.
 > I inserted comments below.

You welcome.

 >> I think any API issues could be worked out.  Are there any programs
 >> you know of,
 >> (yours?), that import pydoc besides the python console?
 >
 > What I did barely qualifies as a hack for my own usage -it won't count-.

It could be these changes will give you a way to do the same thing in a less 
haskish way.


 > From the top of my head, there might be  "ipython" (the excellent
 > interactive console) is possibly using pydoc
 > (in any case, I would say that the authors would be interested in
 > developments with pydoc)

According to the web site, ipython is based on twisted, and is currently still 
limited to python 2.3 and 2.4.  Also, the output of the help() function will not 
change much so I doubt it would be a problem for them.

 > Otherwise a quick search lead to:
 > - "cgitb" (!? - it seems that the HTML formatting functions of pydoc
 > are only in use - wouldn't these functions belong more naturally to
 > "cgi" ?)

Thanks!, These html formatting functions still exist or are small enough to move 
into cgitb, so it will be just a matter of making sure they can be reached.  I 
don't think they will be a problem.


 > - "DocXMLRPCServer" (hey ! it looks like kind-of what I was needing !!!).

Thanks again.  This might be better to move into the pydoc package.  Any opinions?


 > - "happydoc" (reportedly having problems with python 2.4 - I am not
 > sure that it is maintained)

Happydoc does not import pydoc as far as I could tell, so this won't effect them 
in any direct way I think.  They've pretty much implemented everything from 
scratch.  At worse they would just need to copy the parts from the older version 
into their distribution.

I think you got a false positive on this because pydoc is a substring of happydoc.


 > "cgitb" and "DocXMLRPCServer" are both distributed bundled with Python.
 >
 > "cgitb" seems to be mostly using HTML formatting helpers (and that would
 > suggest the need for an HTML-rendering module - may be for a future
 > improvement,  a first step would be separate the rendering/viewing
 > from extraction and modeling of documentation data).

Making sure these still work would be a good sub project for someone a little 
later.  (I'll do it if no one else has time or wants to.)  I'm trying not to 
change thing to drastically.  If the changes are too big, ie... introducing and 
altering a lot of other modules.  Then this will need to move back to the 
python-3000 list.


 > "DocXMLRPCServer" looks (at first sight), like a viewer that would be
 > bundled
 > with pydoc as a sub-module (i.e., module in a package).

Yes, that was my thought too. :-)

But moving it may need to wait until python-3000.  (?)


 >> Pydoc is a fairly complex program and it would definitely help if
 >> others took a
 >> look at various parts and made contributions and or suggestions to
 >> making it better.
 >
 > Well, I stumbled upon your recent posts in python-ideas (that I tracked
 > up the
 > one in python-devel) because I looked into it I thought that it would be
 > a *lot* of work for one person.
 > (more on that in the next inlined comment)

It was tedious going though the module, but now that it's split up into smaller 
parts it shouldn't be too difficult.


 >> I may have also gotten a bit over my head, but I'm willing to stick it
 >> out and
 >> try to get it finished with any suggestions (and help) that any one is
 >> willing
 >> to give me.  There are also too many important issues for me to be
 >> decided, so
 >> this isn't something that can be done in isolation.
 >>
 >> The download link again is:
 >>
 >>      http://ronadam.com/dl/_pydoc.zip
 >
 > I would be willing to help out, as probably others will as well (I
 > found blogs and
 > posts of people discussing pydoc, it might be worthwhile dropping a line to
 > the people - we can discuss that off-list if you wish), but may be at
 > one condition.
 >
 > I do not think it will work as a zip file shuttled around (in my
 > experience).
 > A versioning system would be extremely helpful (SVN, or CVS. would
 > come to my mind).
 > Well, if you are ok with having the source tree hosted in a
 > SVN/CVS/alike I am on
 > (opening an account on sourceforge or savannah -for example- would be
 > the next step then, as it can take few days for a project to be
 > approved)

I don't have any experience with SVN, but it could be an opportunity to learn 
something new.  I have a couple of other projects that could benefit by moving 
them to SVN or CVS like system.

What I intended was to get enough feed back that I could get it to a point where 
it's 90% done and then upload it as a patch where it could be further polished 
up.  To do that, I first need to verify my design goals are the correct 
approach. (see my reply to Ka-Ping.)  If they are, then it's more a matter of 
cleaning up what I've already started.  If not, then it's a bit (or bunch) more 
work and would benefit from having others work on it in a more formal way.

If someone who has more experience with group projects would like to manage it, 
that would be good too.  That may speed things up considerably.


 > I will have a look then.

Great.  :-)


Cheers,
   Ron