This PEP (based on an idea originally put forward back in May [3]) is to not migrate the Python 2 specific deep links at all, and instead adopt a scheme where all URLs presented to users on docs.python.org are qualified appropriately with the relevant release series.

Visitors to the root URL at http://docs.python.org will be automatically redirected to http://docs.python.org/3/ , but links deeper in the version-specific hierarchy, such as to http://docs.python.org/library/os , will instead be redirected to a Python 2 specific link such as http://docs.python.org/2/library/os .

The specific subpaths which will be redirected to explicitly qualified paths for the Python 2 docs are:

The existing /py3k/ subpath will be redirected to the new /3/ subpath.

With this scheme, the following URLs would be presented to users after resolution of any aliasing and rewriting rules:

http://docs.python.org/x/*

http://docs.python.org/x.y/*

http://docs.python.org/dev/*

http://docs.python.org/release/x.y.z/*

http://docs.python.org/devguide

The /x/ URLs mean "give me the latest documentation for a released version in this release series". It will draw the documentation from the relevant maintenance branch in source control (this will always be the 2.7 branch for Python 2 and is currently 3.3 for Python 3). Differences relative to previous versions in the release series will be available through "version added" and "version changed" markers.

The /x.y/ URLs mean "give me the latest documentation for this release". It will draw the documentation from the relevant maintenance branch in source control (or the default branch for the currently in development version). It differs from the status quo in that the URLs will actually remain available in the user's browser for easy copy and pasting. (Currently, references to specific versions that are not the latest in their release series will resolve to a stable URL for a specific maintenance version in the "release" hierarchy, while the current latest version in the release series resolves to the release series URL. This makes it hard to get a "latest version specific URL", since it is always necessary to construct them manually).

The /dev/ URL means the documentation for the default branch in source control.

The /release/x.y.x/ URLs will refer to the documentation of those releases, exactly as it was at the time of the release.