Javadoc style python manual?

[xiong.xu.cn]

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.

Any advice?

Thx,
Xiong

[Ben Sizer]

xi*********@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.
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.

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.

--
Ben Sizer

[Rob Wolfe]

xi*********@gmail.com wrote:

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.

Any advice?

With AcitvePython is distributed the htmlhelp version of python
reference
(ActivePython24.chm). It's really convinient to use.

HTH,
Rob

[db]

On Fri, 08 Sep 2006 01:11:06 -0700, xiong.xu.cn wrote:

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.

Any advice?

Thx,
Xiong

pydoc is something I know, it is included in the standard distibution

[Michele Simionato]

Ben Sizer wrote:

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.

http://docs.python.org/lib/modindex.html, pydoc and ipython are more
than enough for me.

Michele Simionato

[Ben Sizer]

Michele Simionato wrote:

Ben Sizer wrote:

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.

http://docs.python.org/lib/modindex.html, pydoc and ipython are more
than enough for me.

modindex is comprehensive but too 'flat'. Sometimes you want to see all
of one object's methods and properties listed together.

I was unaware of pydoc until this thread; its existence seems to be
buried, somewhat. Looking at pydoc.org (assuming that is a good example
of it in use), it looks more like what the original poster and I might
want, but sadly it's still very inconsistent, with many things
undescribed.

--
Ben Sizer

[Michele Simionato]

Ben Sizer wrote:

Michele Simionato wrote:

Ben Sizer wrote:

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.

http://docs.python.org/lib/modindex.html, pydoc and ipython are more
than enough for me.

modindex is comprehensive but too 'flat'. Sometimes you want to see all
of one object's methods and properties listed together.

I was unaware of pydoc until this thread; its existence seems to be
buried, somewhat. Looking at pydoc.org (assuming that is a good example
of it in use), it looks more like what the original poster and I might
want, but sadly it's still very inconsistent, with many things
undescribed.

--
Ben Sizer

Don't miss IPython, too.

$ ipython
Python 2.4.1 (#2, Aug 25 2005, 18:20:57)
Type "copyright", "credits" or "license" for more information.

IPython 0.6.15 -- An enhanced Interactive Python.
? -Introduction to IPython's features.
%magic -Information about IPython's 'magic' % functions.
help -Python's own help system.
object? -Details about 'object'. ?object also works, ?? prints more.

In [1]: import email.FeedParser

In [2]: email.FeedParser.FeedParser?
Type: classobj
String Form: email.FeedParser.FeedParser
Namespace: Interactive
File: /usr/lib/python2.4/email/FeedParser.py
Docstring:
A feed-style parser of email.

Constructor information:
Definition: email.FeedParser.FeedParser(self, _factory=<class
email.Message.Message at 0xb77f5ddc>)
Docstring:
_factory is called with no arguments to create a new message obj
In [3]: help(email.FeedParser.FeedParser)
Help on class FeedParser in module email.FeedParser:

class FeedParser
| A feed-style parser of email.
|
| Methods defined here:
|
| __init__(self, _factory=<class email.Message.Message>)
| _factory is called with no arguments to create a new message
obj
|
| close(self)
| Parse all remaining data and return the root message object.
|
| feed(self, data)
| Push more data into the parser.
In [4]: email.FeedParser.FeedParser??
Type: classobj
String Form: email.FeedParser.FeedParser
Namespace: Interactive
File: /usr/lib/python2.4/email/FeedParser.py
Source:
class FeedParser:
"""A feed-style parser of email."""

def __init__(self, _factory=Message.Message):
"""_factory is called with no arguments to create a new message
obj"""
self._factory = _factory
self._input = BufferedSubFile()
self._msgstack = []
self._parse = self._parsegen().next
self._cur = None
...

Unfortunately, the nice colors of IPython are lost in the post :-(

Michele Simionato

[Paul Boddie]

Ben Sizer wrote:

xi*********@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/

[John J. Lee]

xi*********@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

[John J. Lee]

"Paul Boddie" <pa**@boddie.org.ukwrites:
[...]

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.

[...]

Why do you expect to get useful docs that way? The canonical Python
stdlib docs live in LaTeX files, not in the docstrings. You may find
some useful bits and pieces in the docstrings too, or you may not.
John

[Paul Rubin]

jj*@pobox.com (John J. Lee) writes:

Why do you expect to get useful docs that way? The canonical Python
stdlib docs live in LaTeX files, not in the docstrings. You may find
some useful bits and pieces in the docstrings too, or you may not.

Yucch. From

http://www.gnu.org/software/emacs/ma...-Criteria.html

"If the on-line documentation string of a function or variable
disagrees with the manual, one of them must be wrong; that is a bug."

I think that's preferable to Python's approach.

[Paul Boddie]

John J. Lee wrote:

>

[epydoc on the standard library]

Why do you expect to get useful docs that way? The canonical Python
stdlib docs live in LaTeX files, not in the docstrings. You may find
some useful bits and pieces in the docstrings too, or you may not.

But wasn't the questioner recommended to use pydoc, help and so on? As
far as I am aware, none of those things look in LaTeX files in order to
provide the documentation that they do dig up. It turns out that pydoc
(in graphical mode) manages to permit introspection of the known
modules on a system in a more presentable fashion than epydoc, although
epydoc is visually much more like javadoc. Still, both tools rely on
docstrings and might be adequate for packages outside the standard
library - it's just a shame that the standard library doesn't lend
itself as greatly to such inspection (with optimal results).

As far as the means of delivering the library documentation is
concerned, my understanding was that the LaTeX format approach wasn't
encouraging as many improvements to the library documentation as was
expected or desired. This is possibly not that surprising given the
docstring-oriented approach I imagine most developers take with their
own API documentation (in Python and through mostly equivalent
mechanisms in other languages).

Paul

[xiong.xu.cn]

Thanks for all replies regard with this question!
I think I will get used to python help system:)
Maybe I will look into epydoc, too...

-Xiong

Michele Simionato 写�：

Ben Sizer wrote:

Michele Simionato wrote:

Ben Sizer wrote:
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.
>
http://docs.python.org/lib/modindex.html, pydoc and ipython are more
than enough for me.

modindex is comprehensive but too 'flat'. Sometimes you want to see all
of one object's methods and properties listed together.

I was unaware of pydoc until this thread; its existence seems to be
buried, somewhat. Looking at pydoc.org (assuming that is a good example
of it in use), it looks more like what the original poster and I might
want, but sadly it's still very inconsistent, with many things
undescribed.

--
Ben Sizer

Don't miss IPython, too.

$ ipython
Python 2.4.1 (#2, Aug 25 2005, 18:20:57)
Type "copyright", "credits" or "license" for more information.

IPython 0.6.15 -- An enhanced Interactive Python.
? -Introduction to IPython's features.
%magic -Information about IPython's 'magic' % functions.
help -Python's own help system.
object? -Details about 'object'. ?object also works, ?? prints more.

In [1]: import email.FeedParser

In [2]: email.FeedParser.FeedParser?
Type: classobj
String Form: email.FeedParser.FeedParser
Namespace: Interactive
File: /usr/lib/python2.4/email/FeedParser.py
Docstring:
A feed-style parser of email.

Constructor information:
Definition: email.FeedParser.FeedParser(self, _factory=<class
email.Message.Message at 0xb77f5ddc>)
Docstring:
_factory is called with no arguments to create a new message obj
In [3]: help(email.FeedParser.FeedParser)
Help on class FeedParser in module email.FeedParser:

class FeedParser
| A feed-style parser of email.
|
| Methods defined here:
|
| __init__(self, _factory=<class email.Message.Message>)
| _factory is called with no arguments to create a new message
obj
|
| close(self)
| Parse all remaining data and return the root message object.
|
| feed(self, data)
| Push more data into the parser.
In [4]: email.FeedParser.FeedParser??
Type: classobj
String Form: email.FeedParser.FeedParser
Namespace: Interactive
File: /usr/lib/python2.4/email/FeedParser.py
Source:
class FeedParser:
"""A feed-style parser of email."""

def __init__(self, _factory=Message.Message):
"""_factory is called with no arguments to create a new message
obj"""
self._factory = _factory
self._input = BufferedSubFile()
self._msgstack = []
self._parse = self._parsegen().next
self._cur = None
...

Unfortunately, the nice colors of IPython are lost in the post :-(

Michele Simionato