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

[Senthil Kumaran]

On Sat, Mar 19, 2011 at 12:48:48PM +1100, Steven D'Aprano wrote:
> In that case, I nominate Michael Foord's documentation of urllib2
> for linking as well:
> 
> http://www.voidspace.org.uk/python/articles/urllib2.shtml
> 
> I am serious, by the way, I think Michael's urllib2 docs are excellent.

Already done! :)
http://docs.python.org/howto/urllib2.html
http://docs.python.org/dev/howto/urllib2.html

But there is a difference. Do you see it is adopted as a howto under
python docs itself and undergoes similar maintenance as any other
document. We had fix some examples in there a couple of times.

I can understand case which Steven is putting forth and I tend to
agree with that. Linking an external resource at various places
consistently (like a footnote in every module doc) is kind of a
deviation from our current practise, there are chances of it getting
backfired with unforeseen scenarios later. (A possible case is if the
external resource undergoes a lag in maintenance and docs get updated
more frequently?) There is case in hand too, Python3 documentation vs
PyMOTW being available only for Python2. 

As such, I am fine with the way things currently are. Stdlib
documentation is for reference and I search for PyMOTW to landup and
look for examples in Doug's documents and I use both of them in
tandem and needless to say, once a particular module becomes more
familiar, I tend to look for reference more than the example.

-- 
Senthil