(original) (raw)

changeset: 4568:c7ba002ca91d user: Nick Coghlan ncoghlan@gmail.com date: Sun Oct 28 00:36:36 2012 +1000 files: pep-0430.txt description: PEP for updating the URL layout on docs.python.org diff -r 3601d079e62a -r c7ba002ca91d pep-0430.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pep-0430.txt Sun Oct 28 00:36:36 2012 +1000 @@ -0,0 +1,200 @@ +PEP: 430 +Title: Migrating to Python 3 as the default online documentation +Version: RevisionRevisionRevision +Last-Modified: DateDateDate +Author: Nick Coghlan ncoghlan@gmail.com +Status: Draft +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. + +While efforts are under way [3_] to improve the general version switching +support in the online documentation, this PEP is technically independent +of those improvements. + + +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 [4_]) 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\`\` would 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\`\`, would instead be redirected to +a Python 2 specific link such as ``http://docs.python.org/2/library/os\`\`. + +The specific subpaths which would be remapped 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 would be remapped 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/release/x.y.z/\*\`\` +* ``http://docs.python.org/devguide\`\` + +The ``/x/`` URLs mean "give me the latest documentation for this release +series``. 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 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). + + +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. + + +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 + (http://mail.python.org/pipermail/python-dev/2012-May/119524.html) + +.. [2] October 2012 discussion + (http://mail.python.org/pipermail/python-ideas/2012-October/017406.html) + +.. [3] Issue for easier access to other version of the same docs page + (http://bugs.python.org/issue8040) + +.. [4] Using a "/latest/" path prefix + (http://mail.python.org/pipermail/python-dev/2012-May/119567.html) + + +Copyright +=========== +This document has been placed in the public domain. /ncoghlan@gmail.com/ncoghlan@gmail.com