[Python-Dev] Pydoc Improvements / Rewrite

Ron Adam rrr at ronadam.com
Mon Jan 8 17:05:45 CET 2007


Laurent Gautier wrote:
> 2007/1/7, Ron Adam <rrr at ronadam.com>:
>> Laurent Gautier wrote:
>> > 2007/1/6, Ron Adam <rrr at ronadam.com>:
> [...]
>> 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.
> 
> Limiting where different people can commit code changes is possible... it's
> just that I am not certain whether sourceforge allows it or not.
> I asked A.M. Kuchling about that.

I'm not concerned about limiting changes to this project.  I want others to work 
on it.  Can write access be *easily* granted to just one cvs sandbox directory, 
for this project, without granting access to other directories in the sandbox or 
trunk?

>> 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.
> 
> I see that you are under Microsoft windows, so you may want to check
> TortoiseSVN.
> (The python project is stored on a SVN server, so it would make sense
> to favor this  one over CVS - in the case the project administrators
> have directory-level control -).

Thank's I'll try TortoiseSVN out. :-)


> Regarding the possibility of jeopardizing something in the repository,
> the directory-level sandbox should only allow you trash your own work
> ;-)
> (but even then, you should always be able to recover from mistakes).

That would be fine then.  But I'll let you decide since you are offering to 
manage getting it set up.


>> >[...]
>>
>> >> 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.
> 
> That's all in the meaning of "some" I guess... ;-)

Yep.

>> 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.
> 
> I am fully on that line, with the remark that thinking about point 5
> early is that
> could make the cut. The exercise will be in avoiding over-complication
> in a design that is not used in the end.
> 
> Reactions on this thread brought a lot of good ideas and pointers to
> existing work.
> It loo

Yes, It does help to have additional view points and references.


>> 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.
> 
> Regarding tests, it is never early enough to think about them (that
> let one write
> code that is actually "test-able").

Right, and thanks for taking more than a casual interest in this. :-)

Cheers,
    Ron




More information about the Python-Dev mailing list