Python Documentation (should be better?)

[Christopher J. Bottaro]

This post is just the culmination of my thoughts and discussions with my
coworkers on Python. If you are not interested, please skip over it.

At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs). I chose to do all mine in Python because I'm a
huge Python fan boy. Naturally, I tried to get my coworkers to try Python.
I made an agreement with one: I write one of my modules in PHP and he will
write one in Python.

After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.

Now for the real kicker. Some of the module documentation doesn't even list
simple use cases or even the entire API. When my coworker came to me with
this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker's reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?

The next complaint isn't really about documentation. Why isn't there a CPAN
or PEAR for Python? So many times I've search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!

Don't get me wrong, I love Python. The language itself is second to none (I
haven't tried Ruby yet), but this experience has left me wondering about
the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.

What do yall think?

 

[hugonz]

I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".

If you're using Windows, then the doc browser included is pretty good
too...

 

[=?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=]

[...]
Funny, the con of Python (documentation) is PHP's strong point.
The PHP manual is extremely easy to navigate and its search feature
works great. Contrast that with Python, where you have to use "the
tutorial" as the manual. Also, the tutorial is just that...a tutorial,
its a NOT a manual.

The tutorial is great IMHO and yes, it is definitely not a
reference guide. But what's wrong with the online library
reference or its pdf equivalent ? And why don't you use the
python.org "search" (top right of the screen) ?

Now for the real kicker. Some of the module documentation doesn't
even list simple use cases or even the entire API.

Sometimes the 'missing' interface is (superficially) hidden
on purpose. Example in doctest about the DocTestCase class
(quoted from the library ref) :

"""
Under the covers, DocTestSuite() creates a unittest.TestSuite out of
doctest.DocTestCase instances, and DocTestCase is a subclass of
unittest.TestCase. DocTestCase isn't documented here (it's an internal
detail), but studying its code can answer questions about the exact
details of unittest integration.
"""

Could you be more specific about the modules/packages
that lack proper examples/documentation ?

When my coworker came to me with
this complaint, my response was "oh, just load the interpreter,
import the module and call dir() on it. Then instantiate some objects
and call dir() on them also". My infatuation with Python had kept me

from realizing the sheer ridiculousness of that method to learn to
use an API. Needless to say, my coworker's reaction to that statement
snapped me out of it. But its the truth. How many of you learn a
module by starting the interpreter
and "playing" around with it and using dir()?

You may also use "help" instead of "dir", or directly
pydoc in a shell:

python>>> help("math")
python>>> help(math) # if 'math' has already been imported
bash$ pydoc math

This kind of documentation system suits me (it is far better
than a raw dir anyway). It supports a 'dotted reference'
description of the path to the objects (ie
package.subpackage.module.holder.object) that is IMHO very
convenient.

Cheers,

SB

 

[Steven Bethard]

After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.
[snip]

What do yall think?

I have to say, I don't really have your troubles with the documentation,
and I hardly ever use dir() in the interactive shell. You mention only
referring to the tutorial. Why don't you check the Language
Reference[1] or Library Reference[2]?

That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.

STeVe

[1]http://docs.python.org/ref/ref.html
[2]http://docs.python.org/lib/lib.html
[3]http://sourceforge.net/tracker/?group_id=5470&atid=355470

 

[Christopher J. Bottaro]

I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".

I guess I mean Python needs a manual, which is basically what the tutorial
serves as, but its not comprehensive and organized like how (I think) a
manual should be.

 

[Christopher J. Bottaro]

After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a
manual. Its not organized like a manual and its not comprehensive like a
manual, hell, raw_input() isn't even mentioned in Chapter 7. Input and
Output.
[snip]

What do yall think?

I have to say, I don't really have your troubles with the documentation,
and I hardly ever use dir() in the interactive shell. You mention only
referring to the tutorial. Why don't you check the Language
Reference[1] or Library Reference[2]?

Cuz I think the Language Reference is really more of a grammer reference and
far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules). There is just the tutorial that serves as the
manual. I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

Kinda funny...I was going to use the email module as an example of a module
that lacks examples...but apparently that has been updated since when I
last used it...=)

That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.

That true, but to be perfectly honest...I don't feel qualified. I'm still a
young'un in this programming game. I'm sure a lot of seasoned devs would
scoff at the documentation I write.

STeVe

-- C

[1]http://docs.python.org/ref/ref.html
[2]http://docs.python.org/lib/lib.html
[3]http://sourceforge.net/tracker/?group_id=5470&atid=355470

 

[=?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=]

"Manual" == scope of the *Lib Reference* + informal style of the
*Tutorial*,

Right ?

Consider non-official manuals such as:
+ http://diveintopython.org/toc/index.html (free)
+ python in a nutshell
+ python cookbook
+ etc.

Cheers,

SB

 

[Steven Bethard]

I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures,

http://docs.python.org/tut/node6.html
or
http://docs.python.org/ref/compound.html

functions,

http://docs.python.org/tut/node6.html#SECTION006600000000000000000
http://docs.python.org/tut/node6.html#SECTION006700000000000000000
or
http://docs.python.org/ref/function.html

classes, inheritance, etc

http://docs.python.org/tut/node11.html
or
http://docs.python.org/ref/class.html


Note that the first examples above are from the tutorial, the second
form the language reference.

Personally, I would think that for 99% of users, going through the
tutorial should be sufficient (it was for me). I only use the language
reference when I need to explain a particular detail of why Python does
something.

Was there something that wasn't in the tutorial that you would have
liked to be? The more specific you can get, the more easily we can
improve the documentation.

That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.

That true, but to be perfectly honest...I don't feel qualified. I'm still a
young'un in this programming game. I'm sure a lot of seasoned devs would
scoff at the documentation I write.

Well then at least file a feature request and indicate what was missing
from the documentation, or what part of it confused you. Even if you
throw in a few phrases of documentation that never get used, at least
they might give the dev who updates the documentation a better idea of
the problem you encountered.

STeVe

 

[=?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=]

[...]

Cuz I think the Language Reference is really more of a grammer reference and
far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules). There is just the tutorial that serves as the
manual. I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

Fair enough. An 'upgraded' tutorial that would include simple
discussion on some 'advanced topics' could be helpful. For example,
there is (almost) no reference to the new-style classes inside the
tutorial, the "yield" keyword and generator stuff is described in
half a page, etc.

SB

 

[Christopher J. Bottaro]

"Manual" == scope of the *Lib Reference* + informal style of the
*Tutorial*,

Right ?

Yes! That sounds good. "Informal style" yes, but "tutorial style" no. I
shouldn't be there to teach like the tutorial, but for reference. And of
course, the manual shouldn't cover the modules like the lib reference does,
but just the language itself and "built in" types.

Ok, here is a concrete example of what I like about the PHP manual and what
people I know have had a hard time with Python. Go to the PHP manual page.
Type "array" in the search input field. It comes back with a page that
briefly describes arrays in PHP and then lists all the functions that have
to do with arrays.

Contrast that with Python. First off there is no "search" mechanism built
into the documentation page (yes I know you can google it, but that just
doesn't feel right). Second off...well, my argument sucks because I
apparently I haven't looked at the Python tutorial recently. But before,
if you looked up "lists" in the tutorial, you got a tutorial style page on
them. If you wanted to see their methods, you had to completely back out
of the tutorial, go to the library reference, then find the section on
"mutable sequences". How unintuitive is that? But like I said, the
tutorial is better now. It lists the methods on list and there is a link
in the dictionary section to the "mapping types" section in the library
reference.

Oh well, I guess all is well.

-- C

 

[George Sakkis]

Cuz I think the Language Reference is really more of a grammer
reference and

far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules). There is just the tutorial that serves as the
manual. I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

If what you miss mostly is a quick way to look up language features,
modules and APIs, the python quick reference is an excellent starting
point, especially for someone new to the language:
http://rgruet.free.fr/PQR24/PQR2.4.html (also linked from
http://www.python.org/doc/ along with other doc sources). It's
available in pdf as well.

George

 

[Steven Bethard]

Contrast that with Python. First off there is no "search" mechanism built
into the documentation page (yes I know you can google it, but that just
doesn't feel right).

Um, are you looking at the current documentation page?

http://docs.python.org/

In the upper right hand corner, I see a box entitled "Search:" and a
button that says "submit".

STeVe

 

[Terry Reedy]

"Manual" == scope of the *Lib Reference* + informal style of the
*Tutorial*,

You, as well as the OP, left out the Language Reference, which is the
manual (by me definition) for the language itself. Chapter 2 of the Lib
Reference on builtin types and functions is essential also and should be
read in its entirety. The rest, to me, is 'need to know' reading,
especially since the addition of string methods.

Consider non-official manuals such as:
+ http://diveintopython.org/toc/index.html (free)
+ python in a nutshell
+ python cookbook
+ etc.

Yes, these and others (the etc) are helpful too, and should not be
discounted just because they are maintained independently of the core
developer group.

Terry J. Reedy

 

[Paul Rubin]

I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".

Some parts of the lib doc are better than others. The only way to
understand SocketServer, for example, is to read the long comment at
the beginning of the source file. I've been wanting to get around to
merging that with the doc writeup and adding some examples.

Tkinter, as well, is practically undocumented as far as the base distro
is concerned, but there's some good docs for it elsewhere on the web.

 

[Paul Rubin]

"Manual" == scope of the *Lib Reference* + informal style of the
*Tutorial*,

I don't care whether the style is formal or informal, the manual
should document the complete interface of the language and library and
right now it doesn't do anything like that.

 

[Terry Hancock]

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules). There is just the tutorial that serves as the
manual. I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

That's probably because

1) The language itself is extremely simple. What you really need is in the
tutorial (or in several books including "Learning Python" from O'Reilly which
I learned from). If you need more than that, then you must be looking for
something fairly picky (like "magic methods" perhaps), so you really do want
to be reading the "Language Reference". Don't overthink it.

2) About 90% of what you want to do in Python is done by using a library
module. Furthermore, it's the 90% you are likely to forget, thus needing
a manual for reference. That's why I regard the "Library Reference" as
"the manual". Don't forget that many "built-ins" are documented here as
well (e.g. the methods of strings*).

There are, of course, numerous introductions to Python which can be freely
downloaded, and several commercial books on the subject. IMHO, the
"manual" is to be the ultimate, most up-to-date, most accurate, and most
detailed source on the language (you go there to check details if something
doesn't work the way your tutorial says it does). Readability is secondary ---
use a third party source for the "friendly" version (not that the Language
or Library References are unfriendly --- they're just concise, IMHO).

Also, Python gives you something most languages don't --- the interactive
interpreter allows you to play around with Python constructs and find out
how any picky details work by trying it out. This is clearly the most
guaranteed accurate way to find out the answer to a syntax or semantic
problem, and it's so easy it's hard to justify the wasted time perusing a
manual for such details. That's why people are frequently recommended
to "ask the interpreter" about such details. This saves a HUGE amount
of time for me --- I'm surprised that you dislike this approach, it seems
extremely practical to me.

*But you do have to remember that strings are documented under "sequences"
this is probably my biggest complaint about the Library Reference --- something
as important as string methods should have its own heading in the top-level
outline. But that's a nitpick, of course.

 

[Skip Montanaro]

Paul> Some parts of the lib doc are better than others. The only way to
Paul> understand SocketServer, for example, is to read the long comment
Paul> at the beginning of the source file. I've been wanting to get
Paul> around to merging that with the doc writeup and adding some
Paul> examples.

Thanks for the suggestion. I just incorporated the module doc string into
the SocketServer doc (CVS HEAD and 2.4 release branch).

Paul> Tkinter, as well, is practically undocumented as far as the base
Paul> distro is concerned, but there's some good docs for it elsewhere
Paul> on the web.

I'll let someone else tackle that one. ;-)

Skip

 

[Christopher J. Bottaro]

Um, are you looking at the current documentation page?

http://docs.python.org/

In the upper right hand corner, I see a box entitled "Search:" and a
button that says "submit".

Oops. I link directly to the tutorial and library reference...=)

STeVe

-- C

 

[Tim Williams]

Hello, I want that the return sentence don't return anything, how can I do
it?. If i do only return it returns None, and pass don't run too.

Can anyone help me?, thanks.
XIMO

Just don't use a return statement at all, or do something like

[function body]
if not val = None:
return val
[end of function]

 

[Grant Edwards]

Just don't use a return statement at all,

That's exactly the same as "return None"