[Python-Dev] Pydoc Improvements / Rewrite

Laurent Gautier lgautier at gmail.com
Mon Jan 8 12:21:30 CET 2007


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 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 -).

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).

>
> >[...]
>
> >> 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... ;-)

> 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


> 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").

>
> [...]


More information about the Python-Dev mailing list