Abstract

This PEP proposes a strategy for migrating the default version of the Python documentation presented to users of Python when accessing docs.python.org from 2.7 to Python 3.3.

It proposes a backwards compatible scheme that preserves the meaning of existing deep links in to the Python 2 documentation, while still presenting the Python 3 documentation by default, and presenting the Python 2 and 3 documentation in a way that avoids making the Python 3 documentation look like a second-class citizen.

Background

With the transition of the overall Python ecosystem from Python 2 to Python 3 still in progress, one question which arises periodically [1, 2] is when and how to handle the change from providing the Python 2 documentation as the default version displayed at the docs.python.org root URL to providing the Python 3 documentation.

Key Concerns

There are a couple of key concerns that any migration proposal needs to address.

Proposal

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:

• /c-api/
• /distutils/
• /extending/
• /faq/
• /howto/
• /library/
• /reference/
• /tutorial/
• /using/
• /whatsnew/
• /about.html
• /bugs.html
• /contents.html
• /copyright.html
• /license.html
• /genindex.html
• /glossary.html
• /py-modindex.html
• /search.html

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

Rationale

There is some desire to switch the unqualified references to mean Python 3 as a sign of confidence in Python 3. Such a move would either break a lot of things, or else involve an awful lot of work to avoid breaking things.

I believe we can get much the same effect without breaking the world by:

1. Deprecating the use of unqualified references to the online documentation (while promising to preserve the meaning of such references indefinitely)
2. Updating all python.org and python-dev controlled links to use qualified references (excluding archived email)
3. Redirecting visitors to the root of http://docs.python.org to http://docs.python.org/3.x

Most importantly, because this scheme doesn't alter the behaviour of any existing deep links, it could be implemented with a significantly shorter warning period than would be required for a scheme that risked breaking deep links, or started to redirect unqualified links to Python 3. The only part of the scheme which would require any warning at all is the step of redirecting the "http://docs.python.org/" landing page to the Python 3.3 documentation.

Namespaces are one honking great idea - let's do more of those.

Note that the approach described in this PEP gives two ways to access the content of the default branch: as /dev/ or using the appropriate /x.y/ reference. This is deliberate, as the default branch is referenced for two different purposes:

• to provide additional information when discussing an upcoming feature of the next release (a /x.y/ URL is appropriate)
• to provide a stable destination for developers to access the documentation of the next feature release, regardless of the version (a /dev/ URL is appropriate)

Implementation

The URLs on docs.python.org are controlled by the python.org infrastructure team rather than through the CPython source repo, so acceptance and implementation of the ideas in this PEP will be up to the team.

References

Copyright

This document has been placed in the public domain.