Laurent Gautier wrote:
> Ron,
>
> I agree that pydoc could benefit a bit from some cleanup.
> As you point it out, the ability to write quick viewers would be
> very helpful. I came across that when wanting to develop script
> on a remote web server for which I only had FTP access: I ended
> up having to study pydoc more than I wanted in order to be able
> to build a display-the-doc cgi.
>
> However having two different modules might not be needed.
I think weather it is two modules or more, or a package, is still an open
issue.
Others have suggested it may be better for it to be package so I'm continuing
in that direction.
> Introspection is probably already available in the separate module
> 'inspect',
> and what a code pydoc would have to do is model the documentation
> (as a tree) and offer convenience function to navigate the data. Beside
> that,
> there would be sub-modules for the different viewers for the documentation
> data - the interactive console being just one of the viewers.
Pydoc currently uses functions from the inspect module along with directly
accessing attributes and other information where it is available. It's not a
replacement for the inspect module.
My first attempt used an xml tree to store the information, but to make that
work requires also storing a fair amount of meta information in the tree as
well. I found parsing the tree and the meta information to be more complex
than
using an objective approach which is (to me) more readable and easier to
extend.
But if you want to try it again, please do. You may come up with something
far better than I did.
> Finally, I would suspect that an API-breaking modification of the module
> would
> need time to be accepted.
I was considering this for python 3.0, but one of the developers suggested it
would be nice to have in python 2.6 and to move the discussion here.
I think any API issues could be worked out. Are there any programs you know
of,
(yours?), that import pydoc besides the python console?
May be the original author of pydoc is
> considering
> changes as well, and joining effort would be possible ?
AUTHOR
Ka-Ping Yee <[EMAIL PROTECTED]>
CREDITS
Guido van Rossum, for an excellent programming language.
Tommy Burnette, the original creator of manpy.
Paul Prescod, for all his work on onlinehelp.
Richard Chamberlain, for the first implementation of textdoc.
Ka-Ping reads python-dev but I'm cc'ing this to him just in case. (I Used his
python-dev email address since I don't know if the above one is current.)
Pydoc is a fairly complex program and it would definitely help if others took a
look at various parts and made contributions and or suggestions to making it
better.
I may have also gotten a bit over my head, but I'm willing to stick it out and
try to get it finished with any suggestions (and help) that any one is willing
to give me. There are also too many important issues for me to be decided, so
this isn't something that can be done in isolation.
The download link again is:
http://ronadam.com/dl/_pydoc.zip
It's not fully functional yet, but does run. Some parts like the command line
file output options still need to be reimplemented. Some output formatting
still
needs to be cleaned up, and the MRO tree parsing section still needs to be put
back in.
One question that I have at the moment is:
* Would it be good to have the "KEYWORD" and "TOPICS" info as included data
objects or files, and possibly use that to generate the python html (and other)
documentation for these? (Instead of the other way around like it is now.)
This would eliminate the requirement to install something extra in order for
help on these items to work.
> L.
>
> PS: I would also not go for a module name deliberately prefixed with "_"
> (as some people might associate that with protected or private objects).
The underscore was just a "temporary" convenience to avoid the name conflict
with the existing module. Weather to reuse the old name or use a new name is
still one of the many open issues I think.
Ron
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
