[Python-Dev] pydoc II

[Laurent Gautier]

Hi,

There was a thread some weeks ago about work on pydoc, with the
admitted aim of proposing something as an upgrade to the current
pydoc.

We had a number of suggestions, on this very list or privately, and we
looked into
having something that would not only retain the capabilities of the
current pydoc
but facilitate customization when it comes to formatting the help, or
process the docstrings.

Looking at things, and implementing along to see how it would look like, we are
coming to something that looks very much like a new implementation... and before
going further I would like to ensure that that does not mean an
automatic "no way".

The obvious question is "why change something that is working ?", and
the answer is as simple as although pydoc is a very helpful, there are
a number
of functionalities that appeared wished so much that other modules appeared.
What is proposed here is along the line of "the same but more extensible".
The pydoc envisioned is both a library for extracting documentation, as well as
few standalone applications using that library (a documentation
browser, an interactive console help... just like pydoc currently
has).

A prototype is being worked on, and I have been looking at code and/or
functionalities in pydoc, epydoc, pydoctor, and ipython (for the
interactive console), and there a lot of nice things in all these
efforts. The name of the game is now to have something that likely to
offer the best of all (although it can be an easy way to get no one
happy in the end).

Hopefully someone kept reading up to here...

Some of the key points so far:

library:
- ability to browse documentation inside module/package files without
loading them
- ability to browse documentation attached to "live" (that is loaded) objects
- documentation API that is independent of whether the object is loaded or not
- low-energy barrier for adding support for "other-than-plain-text" docstrings
- features like searching objects by name, or by content in their doctring

applications:
- HTML server to consult the documentation for installed packages
- interactive console to consults the documentation for installed
and/or loaded objects
- generation of HTML documentation


How does this sound so far ?


Laurent