[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
alexander.belopolsky at gmail.com
Sat Mar 19 23:19:25 CET 2011
On Tue, Mar 15, 2011 at 3:11 PM, Tarek Ziadé <ziade.tarek at gmail.com> 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 so
> people have more examples etc.
I did not know about PyMOTW until now, so 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
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.
I am sure there are instances when a PyMOTW is a valuable addition to
the "official" module documentation, but I think a decision to link it
should be made on a case by case basis by someone who would review
both the official and PyMOTW pages and decide that a link to PyMOTW
adds to the quality of documentation for a given module.
More information about the Python-ideas