[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
Terry Reedy
tjreedy at udel.edu
Fri Mar 18 09:06:10 CET 2011
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
More information about the Python-ideas
mailing list