[Python-ideas] docs.python.org

[Nick Coghlan]

On Sat, Oct 27, 2012 at 6:02 PM, Bruce Leban <bruce at leapyear.org> wrote:
> 2. Pick a stable url for docs and a way for referrers to select the
> referenced version when that matters
>
> Examples:
>     (a) http://docs.python.org/dev/library/os.html#os.walk -- displays
> user's preferred version (see below)
>     (b) http://docs.python.org/dev/library/os.html?version=2.7#os.walk --
> displays version 2.7 if user does not have user's preferred version
>     (c) http://docs.python.org/dev/library/os.html?exactversion=2.7#os.walk
> -- always displays version 2.7 (discouraged unless talking specifically
> about that version)

We can already reference exact versions:

http://docs.python.org/2.6/library/os
http://docs.python.org/2.7/library/os
http://docs.python.org/3.2/library/os
http://docs.python.org/3.3/library/os

For non-current releases, those will redirect to the appropriate
release-specific URL, for the two current releases, it will redirect
to the stable "latest release" URL.

The problem is the current stable URLs for "latest Python 2" and
"latest Python 3" are respectively:

http://docs.python.org/library/os
http://docs.python.org/py3k/library/os

(despite comments elsewhere in the thread, "py3k" does *not* resolve
to the dev docs - those use the "/dev/" prefix in the path component)

It was suggested previously (i.e. more than a year ago) that it would
be better if 2.x/3.x worked as expected so people could update their
links appropriately, and I thought we had agreement on making that
change, but I guess nobody with server access agreed that was the case
(there's no ticket tracker currently in place for the python.org
infrastructure).

Note that I am deliberately limiting my suggestions to those which
require nothing new in the docs theming, just updates to the URL
handling in the web server.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia