Pydoc Rewrite Discussion at doc-sig list.
Ron Adam
rrr at ronadam.com
Sat Apr 14 19:18:36 EDT 2007
Colin J. Williams wrote:
> Ron Adam wrote:
>> If anyone is interested in participating in discussing the details of the
>> PyDoc rewrite/refactoring I've been working on, a discussion is being
>> started on the doc-sig list.
>>
>> Doc-Sig at python.org
>>
>> The goal of this discussion will be to get it to a final finished form so a
>> patch can be submitted and a final discussion can take place on the
>> python-dev list at a later date.
>>
>> Thanks and Regards,
>> Ron Adam
>>
> Are there features which exist or planned for Pydoc and which are not
> available with epydoc?
They are really two different things. Epydoc is an application for
producing documentation, Pydoc is more of a live introspection tool.
Pydoc *is* primarily the console help function. Many users don't realize
that when they use the help() function they are using Pydoc.
Since Epidoc is a stand alone application, it has much more freedom to add
and extend what it does. Probably Epidoc will always be ahead of Pydoc
when it comes to generating separate stand alone documentation.
Pydoc produces interactive documentation as needed, it doesn't normally
produce any files as you use it. For example while you are working on a
project you can be viewing the Pydoc output in a web browser, make changes,
and then refresh the browser page to see those changes.
Same goes for the builtin help() function and interactive help in console mode.
Pydoc can produce both text and html files, but that isn't it's main use.
There are several reasons for rewriting Pydoc. One is that as both a tool
and a library module, it has developed incrementally over time and is
currently limited more so than it should be for both as a tool and as a
library module to be used by other programs. It has also gotten to the
point where it's not as easy to maintain as it could be.
What I'm doing is addressing these issues by making it a package and
breaking it down into more modular parts.
I'm not trying to make a lot of changes to the output as I see that as a
separate issue. But by rewriting the code that produces that output to be
more modular, flexible, and easier to maintain, it will make producing
better output much easier to do.
As a better library tool box, it may be that other tools can use the Pydoc
package as a base to build on. So it is a goal to make the basic parts of
Pydoc extendable and flexible, but at the same time keeping the interface
to each part clear and simple. Some of these parts may be relocated other
packages depending on what they do.
Are there any specific features you are interested in?
Cheers,
Ron
More information about the Python-list
mailing list