[Python-Dev] Pydoc Improvements / Rewrite

Laurent Gautier lgautier at gmail.com
Fri Jan 5 12:20:10 CET 2007


2007/1/5, Ka-Ping Yee <python-dev at zesty.ca>:
[cut]
> 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.

Point well taken. This is very sensible.

I would still try to keep common-and-presenter-independent component.
Rather than a sole distinction console/HTML, I would think of a distinction
between stateless and interactive presenters, and still have the console and
static HTML as specific presenters. The search functions Ron suggested
would be part of that presenter-independent part (and for the refinement,
stateless vs. interactive would make sense for performances).

The distinction may look like an unnecessary complication... but I would
think that it does not have to be complicated, and that the number of practical
things it would allow would make it almost necessary (ah ! delusions ;-) ).
There a number of python editors/consoles/IDE around, some of which
are implemented in python, and having the necessary infrastructute to
let implement
easily documentation presenters would be very nice.

> 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).

Your warning regarding the creation of  a n-th data structure is completely
agreed upon. I also understand your point about the dangers of
overgeneralizing.

> 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.

Having things already split by Ron is probably a good starting base
(and generalization introduced progressively, if agreed upon).

I see that there is debating on the format for documentation strings,
may there is as well room for flexibility regarding how the strings are
utilized.

The search would be not only useful to the python console, but also to
other editors, as well as to editor (as well as python programs),
as well as to stateless presenters (the case I had was to work on a
server (web-hosting) on which I only had FTP access and on which I did
not know the python version or the package installed -hey, what about
an Ajax-capable HTML viewer for the documentation ?) -



Laurent


>
> -- ?!ng
>


More information about the Python-Dev mailing list