[Python-Dev] Pydoc Improvements / Rewrite

[Ron Adam]

Laurent Gautier wrote:
> 2007/1/6, Ron Adam <rrr at ronadam.com>:
>> Laurent Gautier wrote:

> [...]

> I read your comment about having not too many things changed for 2.6.
> (or that will be bumped to 3000).
> 
> A suggestion I would have would be to create an html/htmlrender module
> in the pydoc-package-to-be and start putting all the html formatting 
> function
> (as they are completely independent of pydoc, as far as I can see, over 
> there).

There really isn't as many html specific formatting functions as you might think 
since I used a very consistent format of css tagged definition lists.

In the case of cgitb, it's probably better to copy those functions to it and 
just get rid of the dependency.  If someone does put together a library of 
useful html functions and class's then pydoc, cgitb and other programs can use it.

BTW, all the html specific functions and formatting have already been collected 
in the gethtml.py file.  I've also added more comments to both gettext.py and 
gethtml.py last night, so it should be easier to see how it works.  First look 
though gettext.py to get a general idea of how the info is collected and 
formatted in text, then look at gethtml.py.

      http://ronadam.com/dl/_pydoc.zip


> You can then create wrappers to the original functions including a 
> deprecation
> warning. You can refer to Michael Chermside's recipe for an example of
> implementation with a deprecation decorator -
> http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/391367
> )
> The suggestion above would actually apply to *anything* that is changed
> in pydoc, providing the benefit of allowing the necessary changes while 
> having
> a temporary API to provide back-compatibility.

Yes, that would be good and may be needed, but it's still a ways off.  Lets get 
it to work first, then if it gets approved for inclusion, then how to move it 
into the python distribution (with any needed changes needed for that) can be 
worked out.  First things first, if you know what I mean.


> [...]

>>  > I do not think it will work as a zip file shuttled around (in my
>>  > experience).
>>  > A versioning system would be extremely helpful (SVN, or CVS. would
>>  > come to my mind).
>>  > Well, if you are ok with having the source tree hosted in a
>>  > SVN/CVS/alike I am on
>>  > (opening an account on sourceforge or savannah -for example- would be
>>  > the next step then, as it can take few days for a project to be
>>  > approved)
>>
>> I don't have any experience with SVN, but it could be an opportunity 
>> to learn
>> something new.  I have a couple of other projects that could benefit 
>> by moving
>> them to SVN or CVS like system.
> 
> I have seen A.M.Kuching's suggestion about python's sandbox,
> but I do not know if it would work in the short term. Anyway,
> and at least for the long(er) term, it will make sense to favor SVN
> over CVS (since this is what the python project is using). That rules
> out savannah and leaves us with sourceforge.

I'd like to know more about using the sandbox, I know it would be easy for 
people to read the source there, but who all can have write access to it without 
having write access to other python areas?  I would not mind giving that a try 
if someone who already knows how could point me to the correct how-to 
documentation with some advice on what not to do.

I'm actually more concerned about the what not to do stuff.  I really would not 
like to clobber someone else's work or create problems because of my 
inexperience with CVS.


>[...]

>> If someone who has more experience with group projects would like to 
>> manage it,
>> that would be good too.  That may speed things up considerably.
> 
> I have some experience in it (in companies, and in an open source project)
> I can always file a application for a sourceforge project,
> and can help you with managing it until you feel like taking it on your own
> (or it is merged with the python trunk)

I don't see this as taking a long time if we keep it to cleaning up with some 
API and user interface improvements.

I know there are some here who want a smart parsing engine, which probably would 
take a long term commitment to maintain and fix bugs, etc.  But lets look at the 
actual use's that pydoc serves first.

Use's for pydoc in order of importance and frequency of use:

    1. Console (builtin) help.  ie.. the help() function.
    2. HTML browsing and quick reference.
    3. Document generation in text.
    4. Document generation in html.
    5. Document generation in other formats.  (not currently possible)

I'm concentrating on 1 and 2.  Use cases 3 and 4 are just an easy to do 
byproduct of doing 1 and 2.  I think the cleaning up may make doing 5 possible.

Lets turn the question around.  How well would other document generators supply 
pydoc with the equivalent text of the help() function, interactive help session 
output, and the equivalent html needed for dynamic html browsing?

Also keep in mind the help function is always by default imported into python, 
so keeping that small and relatively simple with a minimum of external 
dependencies is good.


 > I am willing to contribute to the implementation (I suspect that
 > things like unit tests be needed).

Yes, there will need to be some unit tests.  It may even help for those be 
written now.  That would help us identify things that still need to be done.


[...]

> I should have the time during the week-end. I will get back to you 
> off-list.

Cool. :-)

Cheers,
    Ron