News for hackers. Stuff that matters.
Re:I Like PHP by RyanMcGreal on Wednesday August 10, 2011 @02:25PM (#2869509)
Python's got excellent documentation, both official and third party.
Re:I Like PHP by otterley on Wednesday August 10, 2011 @02:32PM (#2869531)
Python itself does, but the third party modules (which do most of the heavy lifting) generally don't. See: Twisted.
Re:I Like PHP by jrockway on Wednesday August 10, 2011 @05:57PM (#2870396)
Perl is a good example where most third-party modules have good documentation. Or at least a SYNOPSIS you can poke, some DESCRIPTION of what the module does, and a few hundred lines of code in the t/ directory that test all the features of the modules.

The one thing I miss in Python is the inability to click "view source" in my web browser to see how a core Python library is implemented. PHP also has this problem. (Code is the best documentation. Learn to read it.)

Re:I Like PHP by shabble on Thursday August 11, 2011 @01:28AM (#2871546)
If you're talking about the search.cpan.org links to source, I'm right there with you.

The only thing I wish they had was a way to pipe it through a highlighter like perltidy with html out. That'd probably just lead to holy wars on formatting/colours though.

Re:I Like PHP by draegtun on Thursday August 11, 2011 @06:05AM (#2872170)
Re:I Like PHP by shabble on Thursday August 11, 2011 @06:23AM (#2872195)
Awesome. search aliases duly updated.
Re:I Like PHP by wulczer on Wednesday August 10, 2011 @04:47PM (#2870115)
Twisted has semi-decent documentation, see

http://twistedmatrix.com/documents/current/api/twisted.html

http://twistedmatrix.com/documents/current/core/howto/index....

http://twistedmatrix.com/trac/wiki/Documentation

It's not as comprehensive and shiny as the core Python docs, but along with the tutorials and examples, it's actually pretty decent.

Re:I Like PHP by masklinn on Thursday August 11, 2011 @05:25AM (#2872093)
There's high variation in quality amongst third-party modules, but the "modern" python community takes documentation quite seriously, there's even a complete site dedicated to nothing but hosting compiled documentation[0]. Projects like Django, Flask, SQLAlchemy or Flask have rather good documentation sets.

[0] http://rtfd.org

Re:I Like PHP by twism on Wednesday August 10, 2011 @02:35PM (#2869549)
Third party documentation doesn't count in this discussion.
Re:I Like PHP by ceejayoz on Wednesday August 10, 2011 @02:43PM (#2869607)
It does when one of the big criticisms of PHP is that it rolls everything into core that'd normally be third-party.
Re:I Like PHP by bad_user on Wednesday August 10, 2011 @04:19PM (#2869991)
Considering how PHP doesn't have anything like Twisted (and this is just one example out of many) ; no, it doesn't count.

Also, I never used a popular Python library for which I haven't found good resources.

My favorite Python library, called NLTK, which has no equivalent in PHP or Ruby or any other platform for that matter, comes with a freaking book that's available for free.

Re:I Like PHP by skrebbel on Wednesday August 10, 2011 @02:32PM (#2869534)
Oh! Well, I must've missed that train (haven't done py for a few years). A couple of years ago, you had to get your info from a mix of a tutorial and a library reference, and most functions were documented with 3-4 sentences max and no examples.

Hmm, that said, that's still exactly what I find on the official Python site (e.g. http://docs.python.org/library/stdtypes.html#string-methods - PHP beats this by lightyears with a single page with examples and comments per function). Which 3rd party thing should I be looking for? (genuinely interested btw - the docs is one thing i dislike about python, and maybe unrightfully so, apparently)

Re:I Like PHP by masklinn on Wednesday August 10, 2011 @02:46PM (#2869613)
> e.g. http://docs.python.org/library/stdtypes.html#string-methods - PHP beats this by lightyears with a single page with examples and comments per function

1. Please explain why you need more explanation of these very basic functions

2. PHP's doc comments are unadulterated garbage

3. When things are worth documenting, they are: http://docs.python.org/py3k/library/collections.html

4. if you truly think string methods are insufficiently documented, it is very easy to contribute to the documentation.

Re:I Like PHP by TylerE on Wednesday August 10, 2011 @03:27PM (#2869788)
Frankly, no. Just no.

The REASON PHP needs a page per function is the sheer number of poorly handled edge cases, version incompatibilities, and gotchas.

Re:I Like PHP by scott_s on Wednesday August 10, 2011 @03:18PM (#2869760)
Maybe you're looking more for a tutorial, and not a reference? I've always found the online Python docs excellent, and provided me with exactly the information I need.