[Python-Dev] pydoc II (original) (raw)
Laurent Gautier lgautier at gmail.com
Sun Mar 11 15:46:01 CET 2007
- Previous message: [Python-Dev] fmod.c
- Next message: [Python-Dev] pydoc II
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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
- Previous message: [Python-Dev] fmod.c
- Next message: [Python-Dev] pydoc II
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]