Pydoc Rewrite Discussion at doc-sig list.

[Ron Adam]

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