Python docs very off-putting

Ranguvar · 2010-02-12 00:09:40

This isn't just a rant, don't worry

So, I haven't been coding anything serious in quite a while... this makes me sad.
I thought, okay, I'll mess around with one of the more newfangled languages and get active in programming once more.
Python seemed the logical choice, so I gathered up some tutorials and waded in...

Until I hit the core library docs. Ouch.

The language I (sadly) have the most experience with is Java, and while Javadocs may be painful to write, I never released how much I came to love them.
Extremely structured, precise, and thorough...

Python's docs appear to be none of these things.

There are the docs here, which at first seemed to me to be a rough overview of the libraries, but upon further inspection may actually be official definitions? Not nearly as structured as the Javadocs, and much more painful to wade through.

There's also the documentation served up by the pydoc program.
While much more rigorous and structured in appearance, it also feels half-done; a slipshod effort.
It simply feels wrong, and every minute I spend looking at pydoc pages, I spend in discomfort.
Sounds weird, but it's true -- anyone understand what I mean? That, and it's downright garish looking.

Perhaps it's just me? So I went to see what kind of docs Ruby offered, and I am very pleased.
Not as good IMO as the Javadocs (and I hate praising them for some reason, but it's true xD), but that may be attributed to experience alone, and preference to the eyes; we shall see.
In any case, Ruby's docs are vastly superior to Python's. Framed, logical, tons of examples... fantastic.

Anyone know any alternatives to the Python doc system? I'm very tempted to just learn Ruby right now...

Trent · 2010-02-12 00:20:40

I don't really understand what you dislike about the Python documentation. It may not be quite as polished as the official Java API, but I think it's quite as useful (plus without Javadoc's lack of a convenient search facility and obnoxious use of frames).

One thing you might want to consider is that the link you provided is for Python 3.1, which while stable is still not as common as the older Python 2.6 branch, and is probably marginally less helpful given that the documentation is community supported.

AlexS · 2010-02-12 00:34:28

Ranguvar wrote:

Anyone know any alternatives to the Python doc system? I'm very tempted to just learn Ruby right now...

Why don't you go for Ruby? If that clicks better with you...

Personally I don't have a very structured way of accessing the documentation in python, so I can't really help you there. I use mostly the Ipython shell wich provides an integrated help (you type any object + ?) to access the docstrings, object?? to see the source code etc, or then I just look for the official docs or google my issue.

Of course, if there is a more efficient way, I'm curious to learn about it.

Ranguvar · 2010-02-12 00:36:53

All the same, I'd rather not learn an older version of Python, as little as the differences may (or may not) be, simply because the new version does not have good docs. That doesn't speak well for the language, it implies that might be the case in future releases as well.
I'm not even sure 2.6 does have better docs.

Personally, I love the frames of the Java API It's one of the few places I think frames serve a purpose. Docs need to be highly structure, like the Java API is.
And while it is true that the Java API lacks a search feature, I've been able to overcome that with simple Google site-search.

But, here are some specific issues I have with the Python docs:
-) The Standard Library page is formatted like a tutorial, I feel, more than a reference. Modules are sorted by category of function, and while that seems a minor difference from straight alphabetical listing, it already feels off to me. And then, in the specific module pages, things just feel... loose. Little to no examples, curosy description of each function at best. Where the Javadocs tended to pore over specifics and edge cases for each function, Python seems to only summarize the usage.
-) The pydoc pages are downright nasty to look at, and while feeling much more like reference than the Standard Library pages... I don't really know. It still feels unorganized, and still feels like a poor man's documentation, so to speak.

I really wish this wasn't so feel-based, because I _want_ to enjoy Python's docs, I'm not a man on a mission to diss Python or anything xD
Is there anyone out there who feels the same as me? Did you go on to enjoy Python somehow?

damjan · 2010-02-12 00:43:49

Ranguvar wrote:

-) The Standard Library page is formatted like a tutorial, I feel, more than a reference. Modules are sorted by category of function, and while that seems a minor difference from straight alphabetical listing, it already feels off to me. And then, in the specific module pages, things just feel... loose. Little to no examples, curosy description of each function at best. Where the Javadocs tended to pore over specifics and edge cases for each function, Python seems to only summarize the usage.

The python documentation is much better than the Java for me... but anyway here's your alphabetical reference for you http://docs.python.org/3.1/modindex.html

Ranguvar wrote:

Is there anyone out there who feels the same as me?

No

Ranguvar wrote:

Did you go on to enjoy Python somehow?

Yes

And you don't need that much documentation as you need with Java.. just fire up you python interpreter and use it (well ok, setup a completion first http://code.activestate.com/recipes/496822/)

sr · 2010-02-12 08:01:53

damjan wrote:

And you don't need that much documentation as you need with Java.. just fire up you python interpreter and use it (well ok, setup a completion first http://code.activestate.com/recipes/496822/)

Um, why not just use ipython as the interactive shell?

damjan · 2010-02-12 15:18:09

sr wrote:

Um, why not just use ipython as the interactive shell?

Ah right,
I personally don't use ipython since it has some problems with unicode (which I use a lot) - so I forgot about that sollution

Arch Linux

#1 2010-02-12 00:09:40

Python docs very off-putting

#2 2010-02-12 00:20:40

Re: Python docs very off-putting

#3 2010-02-12 00:34:28

Re: Python docs very off-putting

#4 2010-02-12 00:36:53

Re: Python docs very off-putting

#5 2010-02-12 00:43:49

Re: Python docs very off-putting

#6 2010-02-12 08:01:53

Re: Python docs very off-putting

#7 2010-02-12 15:18:09

Re: Python docs very off-putting

Board footer