On 3/18/2011 1:50 AM, Tarek Ziadé wrote:
I don't know about any other place where there's such an exhaustive documentation of the stdlib.
It may well be the broadest collection on the net. Indeed, it is so broad that he is having it published as a commercial book (Amazon is taking preorders). But that does not make each exposition the best there is for each and every module. I have elsewhere seen some pretty in-depth articles on particular modules. In any case, as I believe Doug acknowleded, it would be inappropriate to promote one particular book in the manuals. What this discussion has so far ignored is that there is no such thing as 'the stdlib'. There are multiple Python versions and releases, and we have this thing called Python 3, which is a bit but significantly different from Python 2. Though the web pages do not say much that I found, the examples are for (mostly unspecified) Python 2. The book promo blurb specifically says 2.7, so I presume he tested and updated as necessary. (Probably not too much was needed since 2.x code is mostly forward compatible up to 2.7). I have no idea if he added new material for new features added late in Py2. For instance, an up-to-date discussion of difflib should include an example showing the need for the SequenceMatcher autojunk parameter added in 2.7.1 to fix the bug independently discovered and reported by multiple people. In any case, Python 3.x manuals should have examples that run with 3.x and not reference Python 2 code.
Every module we have, have more examples in Doug's work than in the stdlib doc itself or elsewhere.
There are a lot of modules to check;-).
I think this doc is the best one we have and not pointing to it is too bad ihmo.
Do it on the wiki, as I suggested. But do specify that it is Python 2 code.
Le 17 mars 2011 18:48, "Steven D'Aprano" <steve@pearwood.info <mailto:steve@pearwood.info>> a écrit :
Terry Reedy wrote:
On 3/17/2011 7:19 PM, Senthil Kumaran wrote:
On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:
As I told Doug during Pycon, I think it would be a good idea to link his PyMOTW pages to our modules documentation in docs.python.org <http://docs.python.org> so people have more examples etc.
Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.
What he said.
With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?
I wouldn't mind having a prominent "External resources" page in the Python docs, if it is actively maintained and doesn't turn into a bunch of dead links in 12 months time.
Or obsolete links to code that is not updated, as is most often the case. One of the reasons for doc patches is to keep up with code changes.
But I have grave doubts about linking to an external site all through the module documentation, no matter how useful it is. Who controls the external content?
The external author. -- Terry Jan Reedy