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

[Alexander Belopolsky]

On Sun, Mar 20, 2011 at 2:33 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> .. but can anyone cite a case where PyMOTW is
> actually *that* wrong?

Didn't I do it in my first reply to this thread?

"""
.. I visited a page on the
module that I am well familiar with, the datetime module.   On a
cursory review, I don't think PyMOTW adds much to an already rather
extensive docs.python.org documentation.  One section, "Combining
Dates and Times" struck me as not very clear.  It starts with an
example:

print 'Now    :', datetime.datetime.now()
print 'Today  :', datetime.datetime.today()
..

$ python datetime_datetime.py
Now    : 2008-03-15 22:58:14.770074
Today  : 2008-03-15 22:58:14.779804
..

Why would someone interested in combining dates and time would like to
know two subtly different functions that return current time in a
datetime object?  The surrounding text does not explain the difference
between datetime.now() and datetime.today().

Overall I am -1 on linking PyMOTW datetime page from datetime documentation.
"""

Note that my "-1" is limited to linking from the datetime module
documentation.  Having not read any other PyMOTW pages, I have no
basis to form an opinion on whether links to those other pages will
improve reader experience.

The datetime module may be unique because it actually suffers from too
much documentation rather than the lack of it.  The official datetime
documentation and its PyMOTW page are not complimentary. They cover
the same material in different styles.  Some users are better off
reading just PyMOTW, others may prefer the official doc.  I don't
really see much incremental value from reading both.

Note that it looks like PyMOTW author intended his pages to be
self-contained rather than a compliment to the official doc.  There is
no link from PyMOTW datetime page to
http://docs.python.org/library/datetime.html.

PS: The PyMOTW datetime page is at
http://blog.doughellmann.com/2008/03/pymotw-datetime.html.

PPS:  I don't think the PyMOTW datetime page is current for 2.7.  This
page seems to be 3 years old and 2.7 have seen a few additions to the
datetime module.