Python Documentation Blows!

[Adam T. Gautier]

OK, First off I am new to Python but I am a convert. I sat down and
wrote two medium complexity applications in Python from scratch and
learning the language in a few days. If I were to do this in C++ and/or
Java it would have taken atleast a month (Rember I was also learning the
Python language). But, I am sick of the documentation! I don't really
use too many Java example applications when I am writing in Java because
(1.) I have been writting in Java since it was called Oak and 2.) I have
the JavaDocs that give me a good grounding as to what the
package/class/function/const is doing). Is there anythin comperable for
Python? It is a shame that the only limitation of a great is
documentation. Is there a project that is trying to do this? Am I
completely off my rocker? Is the Tutorial and Module documentation on
python.org enough? What would it take to develop an JavaDoc like
repository. I don't know much about the PyPI but is a requirement
documentation? What I think would be cool is a PyPI wiki that is
dedicated to to documentation. When a module is submitted it is sent
through a dog auto-gen that generates wiki pages. The wiki pages would
be a reference page(s) (think javadoc), an example code page(s), and a
tutorial thread page(s). Just the refrence page would be auto generated
and the example and tutorial page(s) could be created by the developer
and/or the community in very wiki like style. What do y'all think?

[Kevin Altis]

Are you looking for something dynamic and formatted like pydoc? If so, it is
included with Python, so you can run your own server and pick up the doc
strings in your own modules and packages. There is also a public server for
standard libs.

http://pydoc.org/2.3/

Here's an example for the os module.

http://pydoc.org/2.3/os.html

ka

"Adam T. Gautier" <ad**********@yahoo.com> wrote in message
news:ma**************************************@pyth on.org...

OK, First off I am new to Python but I am a convert. I sat down and
wrote two medium complexity applications in Python from scratch and
learning the language in a few days. If I were to do this in C++ and/or
Java it would have taken atleast a month (Rember I was also learning the
Python language). But, I am sick of the documentation! I don't really
use too many Java example applications when I am writing in Java because
(1.) I have been writting in Java since it was called Oak and 2.) I have
the JavaDocs that give me a good grounding as to what the
package/class/function/const is doing). Is there anythin comperable for
Python? It is a shame that the only limitation of a great is
documentation. Is there a project that is trying to do this? Am I
completely off my rocker? Is the Tutorial and Module documentation on
python.org enough? What would it take to develop an JavaDoc like
repository. I don't know much about the PyPI but is a requirement
documentation? What I think would be cool is a PyPI wiki that is
dedicated to to documentation. When a module is submitted it is sent
through a dog auto-gen that generates wiki pages. The wiki pages would
be a reference page(s) (think javadoc), an example code page(s), and a
tutorial thread page(s). Just the refrence page would be auto generated
and the example and tutorial page(s) could be created by the developer
and/or the community in very wiki like style. What do y'all think?

[Roger Binns]

> What would it take to develop an JavaDoc like repository.

Have you seen what epydoc produces? Here is an example:

http://epydoc.sourceforge.net/stdlib/

I have found *by far* that the best docs are for PHP.
It has little to do with the actual official content
(which is fairly complete and well written and almost always
includes an example), but a lot to do with how anybody can
annotate the pages, wiki style. Here is an example for
the sort function:

http://us2.php.net/manual/en/function.sort.php

Having all those comments is really helpful, and they also
help for updating the documentation. If there are a lot
of comments against a page then the main body really
needs some more work!

(And for those of you who don't know PHP, you will find
the commentary confusing. This is because one of the
authors of PHP decided that a list is the same thing
as a dict with numeric keys, and so PHP only has a
dict type that behaves like lists and dicts. I
won't even mention the tripe equals sign operator!)

Roger