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

[Doug Hellmann]

On Mar 20, 2011, at 11:42 AM, Alexander Belopolsky wrote:

> 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.

The canonical version of that page is http://www.doughellmann.com/PyMOTW/datetime/. You will find a link to the stdlib docs, as well as some other useful date-related docs and tools, in the "See also" section at the bottom of that page.

If you are going to review the content page by page, please look at the versions of the articles under http://www.doughellmann.com/PyMOTW/

Doug