[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.

[Terry Reedy]

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 at pearwood.info
> <mailto:steve at 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