Javadoc style python manual?

[Paul Boddie]

Ben Sizer wrote:
> xiong.xu.cn at gmail.com wrote:
> > I'm new to python and I'm from the java world.
> > Though I love to learn python, I'm not very comfortable with the python
> > documentation.
> > Because when i read jdk doc, i can see the class hierachy, class
> > member, class methods etc in html docs. It's very easy for me to
> > understand the Java language.

I was going to recommend running something like epydoc [1] over the
standard library, but this has its pitfalls.

> > But in python, i find it kind of inconvient.
>
> My advice is to get used to it... the Python docs are not arranged in
> the hierarchical fashion because there isn't any real hierarchy to
> speak of. Python does not rely heavily on inheritance like Java does.
> Instead, it is used in just a few places, more like the C++ standard
> library than the Java library.

Generating API documentation using epydoc really shows this aspect of
the Python standard library: a huge list of names (sched, sets,
sgmllib, shelve, shlex, shutil, site, stmpd, smtplib, sndheader,
socket, sre, ...) which have little inherent organisation on their own.

> I agree that the Python docs aren't quite as effective as reference
> material due to the lack of simple function and method lists though. I
> don't know if there's a solution to that anywhere.

Well, I used a very simple approach to get epydoc to format the
standard library documentation:

epydoc --parse-only --output=apidocs \
  `find Lib -name test -prune -o -name "*.py" -print`

Better usage of the find command could be made, and the resulting
process occupied over 0.5GB before producing 581MB of API documents on
disk. The resulting output reveals some major differences between some
modules and in the quality of the documentation; for example, lots of
empty docstrings cannot always be explained away by the --parse-only
mode employed by epydoc in this case.

Certainly, those with ideas of reorganising the standard library ought
to consider the perspective of the questioner, along with the
possibilities for generating documentation using the various tools
available, in order to find inspiration in such matters.

Paul

[1] http://epydoc.sf.net/