Javadoc style python manual?

[John J. Lee]

xiong.xu.cn at gmail.com writes:

> Hi there,
> 
> 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.
> But in python, i find it kind of inconvient.

Are you talking about the Python standard library (the "stdlib"), or
the set of all Python modules in the world?  The stdlib docs have a
pretty rigid format (though a few modules do vary -- and I don't in
principle begrudge authors some wiggle room, to allow them to say what
they want to say more clearly).  It's just a different format to Java.
That's not *always* a capital offence ;-)

Outside any one project, in general, it has always seemed 10x more
important to me that the docs are set out in a way that suits that
project than it is to conform to some global standard.  In fact, some
peoples' complacent assertions that Python docs are inferior for this
reason really winds me up ;-)  Mind you, the last person who said that
to me was also Chinese, and I guess I can understand that, if Python
documentation were written in Chinese, the relative benefits of
flexibility and consistency in doc structure would be very different
for me!

In a few years it will be us English monoglots who will have to learn
Chinese to read *your* docs :-)

I have to say that, very recently, I've found making use of the
various API doc tools in Python of pretty painful, though -- but that
pain is precisely because of my decision to do exactly what's right
for my project, seeing little value -- other than implementation
convenience -- in following some global standard.  If I just wanted
standard input and output formats, it is just as easy as in the Java
world -- for example, epydoc supports JavaDoc syntax (amongst other
formats), and PythonDoc follows JavaDoc's syntax fairly closely.

(Personally, I ended up using epydoc with my own patched HTML output
module, to get simpler and fewer pages out of it.  PythonDoc is nice
for being far simpler, but I hate the XML-ish markup syntax.)

The Perl story used to be that the POD format was great because it
made people actually sit down and write docs.  I can't say I've
noticed it stopping Python module authors writing docs, though:
docstrings and plain text or HTML work pretty well as a "never mind
the format, sit down and write the **** docs" format.

foolish-consistency-and-all-that-ly y'rs


John