[Python-Dev] Pydoc Improvements / Rewrite

Phillip J. Eby pje at telecommunity.com
Sat Jan 6 09:09:13 CET 2007


At 12:16 AM 1/6/2007 -0500, Barry Warsaw wrote:
>If you've already explained it, that's fine, but if not, could you
>outline what you have against epydoc?

The last I tried to work with it, it had even more hardcoded typechecking 
than pydoc does, spread out over more of the code base.  Also, over at 
OSAF, I've been repeatedly called upon to sort out some peculiarity in how 
it discovers things or how it handles types it doesn't recognize.

My net impression has been that it's very brittle, even more so than pydoc.

On the plus side, there are some very good ideas and a *lot* of good 
execution in there, but its extensibility has historically struck me as 
non-existent.

To be fair, the last time I had to deal with any problems with it at OSAF 
was almost a year ago, if memory serves.  I don't know if anything has 
improved in it since then.

The last time I seriously analyzed its internal architecture was several 
years ago (maybe 5?) when I was investigating it as an alternative to 
HappyDoc for doing PEAK's API documentation.  I could never get it to work 
on anything but a small subset of PEAK without crashing in any of several 
ways, including segfaulting its GUI!  It had built into it a variety of 
restrictive assumptions about how programs are structured that were not 
compatible with what I was doing.  pydoc at least only crashed when dealing 
with metaclass instances, but I believe that was fixed in 2.3 or a late 
2.2.x release.

Anyway, I like the *idea* of epydoc and a lot of its execution, but IMO it 
needs just as much work as pydoc, if not more.



More information about the Python-Dev mailing list