Permalink
Cannot retrieve contributors at this time
| PEP: 430 | |
| Title: Migrating to Python 3 as the default online documentation | |
| Version: $Revision$ | |
| Last-Modified: $Date$ | |
| Author: Nick Coghlan <ncoghlan@gmail.com> | |
| BDFL-Delegate: Georg Brandl | |
| Status: Final | |
| Type: Informational | |
| Content-Type: text/x-rst | |
| Created: 27-Oct-2012 | |
| 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. | |
| Don't Confuse Beginners | |
| ----------------------- | |
| Many beginners learn Python through third party resources. These resources, | |
| not all of which are online resources, may reference in to the python.org | |
| online documentation for additional background and details. | |
| Importantly, even when the online documentation is updated, the "version | |
| added" and "version changed" tags usually provide enough information for | |
| users to adjust appropriately for the specific version they are using. | |
| While deep links in to the python.org documentation may occasionally break | |
| within the Python 2 series, this is very rare. | |
| Migrating to Python 3 is a very different matter. Many links would break due | |
| to renames and removals, and the "version added" and "version changed" | |
| information for the Python 2 series is completely absent. | |
| Don't Break Useful Resources | |
| ---------------------------- | |
| There are many useful Python resources out there, such as the mailing list | |
| archives on python.org and question-and-answer sites like Stack Overflow, | |
| where links are highly unlikely to be updated, no matter how much notice | |
| is provided. | |
| Old posts and answers to questions all currently link to docs.python.org | |
| expecting to get the Python 2 documentation at unqualified URLs. Links from | |
| answers that relate to Python 3 are explicitly qualified with ``/py3k/`` in | |
| the path component. | |
| 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. | |
| Presented URLs | |
| -------------- | |
| 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. | |
| The developer's guide is not version specific, and thus retains its own | |
| stable ``/devguide/`` URL. | |
| 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 | |
| ========== | |
| .. [1] May 2012 discussion | |
| (https://mail.python.org/pipermail/python-dev/2012-May/119524.html) | |
| .. [2] October 2012 discussion | |
| (https://mail.python.org/pipermail/python-ideas/2012-October/017406.html) | |
| .. [3] Using a "/latest/" path prefix | |
| (https://mail.python.org/pipermail/python-dev/2012-May/119567.html) | |
| Copyright | |
| =========== | |
| This document has been placed in the public domain. |