[Python-Dev] Pydoc Improvements / Rewrite

Ka-Ping Yee python-dev at zesty.ca
Thu Jan 4 23:49:44 CET 2007


Hi Ron and Laurent,

I welcome attempts to improve pydoc (especially since I don't have
much time to work on improving it myself).  I definitely agree that
moving to CSS is long overdue, though I would like some input on
the style of the produced pages.

It's probably a good idea to explain how pydoc got to be the way
that it is.  The module boundary between inspect and pydoc is a
pretty clear one, intended to isolate pydoc from future changes
to Python's introspection features (such as attributes on internal
types like frames and functions).

On the other hand, I've often seen the question of why pydoc does
both text and HTML generation instead of generating some intermediate
data structure from which both kinds of output are produced.  The
answer is: I tried it.  The result turned out to be longer than
I expected and needlessly more complicated than what we have now.
It may be that a better job could have been done, but I think there
is a rational basis for why it turned out that way.

The Python objects themselves already are a data structure containing
all of the information we need.  I discovered that translating this
data structure into another data structure and then producing text
or HTML was more work than simply producing text or HTML.  With CSS,
the last step gets even easier and so the intermediate stage becomes
even less necessary.  Also, the intermediate step required me to
essentially invent an API, and I decided that I trusted the stability
of Python's API more than that of some API I invented just for this.

This is not to say that text and HTML generation can't be separated;
it's just a caution against attempting to overgeneralize by creating
an intermediate format.  I'm glad you backed away from XML (or I'd
have warned you that processing the XML would be a lot of extra work).

The inspect module was intended to pull out as much as possible of
the extraction functionality that's shared by the text and HTML
documentation generators.  But pydoc is still big.  At the time I was
proposing pydoc for addition to the standard library, I didn't want
to pollute the top-level module namespace with too many names, so I
tried hard to minimize the number of modules.  And of course it has
grown since then with bits of new functionality and support for new
language features in Python.

But now if a package is being considered, it makes sense to split
out some of the pieces (as you have done), such as the web server,
the search function, and the interactive interpreter help prompt.
It may even enable pydoc to provide search from the interactive help
prompt, which would be a nice feature!  The package could contain
several modules for ease of maintenance, while still providing a
single, convenient command for running pydoc from the Unix prompt.


-- ?!ng


More information about the Python-Dev mailing list