peps: c7ba002ca91d (original) (raw)

Mercurial > peps

changeset 4568:c7ba002ca91d

PEP for updating the URL layout on docs.python.org

Nick Coghlan ncoghlan@gmail.com
date Sun, 28 Oct 2012 00:36:36 +1000
parents 3601d079e62a
children d27bd31d44b7
files pep-0430.txt
diffstat 1 files changed, 200 insertions(+), 0 deletions(-)[+] [-] pep-0430.txt 200

line wrap: on

line diff

new file mode 100644 --- /dev/null +++ b/pep-0430.txt @@ -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[](#l1.136) +will be available through "version added" and "version changed" markers.[](#l1.137) +[](#l1.138) +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

+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

+.. [2] October 2012 discussion

+.. [3] Issue for easier access to other version of the same docs page

+.. [4] Using a "/latest/" path prefix

+ +Copyright +=========== +This document has been placed in the public domain.