473,847 Members | 1,830 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Javadoc style python manual?

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

Sep 8 '06 #1
12 4445
xi*********@gma il.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

Sep 8 '06 #2

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

Sep 8 '06 #3
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

Sep 8 '06 #4
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

Sep 8 '06 #5
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

Sep 8 '06 #6

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.FeedParse r

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

Constructor information:
Definition: email.FeedParse r.FeedParser(se lf, _factory=<class
email.Message.M essage at 0xb77f5ddc>)
Docstring:
_factory is called with no arguments to create a new message obj
In [3]: help(email.Feed Parser.FeedPars er)
Help on class FeedParser in module email.FeedParse r:

class FeedParser
| A feed-style parser of email.
|
| Methods defined here:
|
| __init__(self, _factory=<class email.Message.M essage>)
| _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.FeedParse r.FeedParser??
Type: classobj
String Form: email.FeedParse r.FeedParser
Namespace: Interactive
File: /usr/lib/python2.4/email/FeedParser.py
Source:
class FeedParser:
"""A feed-style parser of email."""

def __init__(self, _factory=Messag e.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

Sep 8 '06 #7
Ben Sizer wrote:
xi*********@gma il.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/

Sep 8 '06 #8
xi*********@gma il.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

Sep 8 '06 #9
"Paul Boddie" <pa**@boddie.or g.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
Sep 8 '06 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

0
1655
by: Dean A. Hoover | last post by:
I noticed in the sun sdk javadoc documentation for, say java.sql.PreparedStatement, that class names are not expanded. For example, the setString method takes a java.lang.String as one of its arguments. This is shown in the html as String. When I run javadoc, it expands all of the class names. I want them shortened like the standard documentation, but I can't seem to find the option to do it. BTW, I am using ant to run javadoc, if that...
1
10251
by: Krusty276 | last post by:
I'm getting this error when trying to compile javadoc in ant from my buildxml: Any ideas? C:\umg\java\web\dbtest\WEB-INF\src\build.xml:64: Javadoc failed: java.io.IOException: CreateProcess: javadoc.exe -d C:\umg\java\web\dbtest\WEB-INF\doc\api -classpath C:\umg\java\web\lib\servlet-api.jar;C:\umg\java\web\lib\struts.jar;C:\umg\ja va\lib\umg-db.jar -sourcepath C:\umg\java\web\dbtest\WEB-INF\src -version -author
1
7632
by: Prakash | last post by:
Hi, I want to generate the JDK API using Javadoc. I have installed java 1.4.2 in WINDOWS. Since i don't have frequent access to the Net, i want to generate the Java API Help using javadoc.But I was unsuccessful in that. Can u give me the exact command for doing so? I had tired:
3
2374
by: Olaf Meding | last post by:
I played a little with happydoc and pydoc and wonder which one I should use. Also, is there a better documentation general available (I am spoiled by javadoc). Lastly, I could not find good documentation for either happydoc or pydoc. Thanks. Olaf
1
2142
by: Alessandro Crugnola | last post by:
Hi all, i need to use a regular expression to match javadoc style comments in a file, something like /** * Constructs a new Call instance. * * @param object the object the Function shall be executed on * @param func the Function that shall be executed * @throws IllegalArgumentException if neigther the object or the function is not available.
12
1596
by: Vaibhav | last post by:
I recently heard about 'new-style classes'. I am very sorry if this sounds like a newbie question, but what are they? I checked the Python Manual but did not find anything conclusive. Could someone please enlighten me? Thanks!
5
7805
by: GoodMorningSky | last post by:
In java I can make documentation of all API I created. In C#, there is tags such as <summary> for documentation. However I don't know the tool like java tool. How to do so? Thank you.
12
1959
by: Ilias Lazaridis | last post by:
Another topic has raised the need of a deeper teach-in. Where can I find _compact_ documentation about * Differece between New Style / Old Style Classes Are there any documents available (again: compact ones) which describe unification attemps subjecting * New Style Classes
2
4279
by: rednarjess | last post by:
Hello every body; When I want to generate the Javadoc for my project, The result is fine at the bigining of the generating init: Generating Javadoc Javadoc execution Loading source file D:\workspace\JavaApplication4\src\javaapplication4\Main.java... Constructing Javadoc information... Standard Doclet version 1.6.0 Building tree for all the packages and classes...
0
9882
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main usage, and What is the difference between ONU and Router. Let’s take a closer look ! Part I. Meaning of...
0
10645
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that captivates audiences and drives business growth. The Art of Business Website Design Your website is...
1
10706
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For most users, this new feature is actually very convenient. If you want to control the update process,...
0
10335
tracyyun
by: tracyyun | last post by:
Dear forum friends, With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each protocol has its own unique characteristics and advantages, but as a user who is planning to build a smart home system, I am a bit confused by the choice of these technologies. I'm particularly interested in Zigbee because I've heard it does some...
0
9481
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development project—planning, coding, testing, and deployment—without human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then launch it, all on its own.... Now, this would greatly impact the work of software developers. The idea...
0
7053
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
5719
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in the same network. But I'm wondering if it's possible to do the same thing, with 2 Pfsense firewalls...
0
5909
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
4524
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.