iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify what 'latest version' means, mark Georg as PEP czar and bump status back to Draft until Georg gives a +1 on the redirection of /dev/ URLs

This commit is contained in:
Nick Coghlan 2012-10-28 21:54:33 +10:00
parent 15206b75a3
commit 2c85e597bc
1 changed files with 31 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
pep-0430.txt
View File

@ -3,7 +3,8 @@ Title: Migrating to Python 3 as the default online documentation
Version: $Revision$ Version: $Revision$
Last-Modified: $Date$ Last-Modified: $Date$
Author: Nick Coghlan <ncoghlan@gmail.com> Author: Nick Coghlan <ncoghlan@gmail.com>
Status: Final BDFL-Delegate: Georg Brandl
Status: Draft
Type: Informational Type: Informational
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 27-Oct-2012 Created: 27-Oct-2012
@ -85,13 +86,13 @@ This PEP (based on an idea originally put forward back in May [4_]) is to
scheme where all URLs presented to users on docs.python.org are qualified scheme where all URLs presented to users on docs.python.org are qualified
appropriately with the relevant release series. appropriately with the relevant release series.
Visitors to the root URL at ``http://docs.python.org`` would be automatically Visitors to the root URL at ``http://docs.python.org`` will be automatically
redirected to ``http://docs.python.org/3/``, but links deeper in redirected to ``http://docs.python.org/3/``, but links deeper in
the version-specific hierarchy, such as to the version-specific hierarchy, such as to
``http://docs.python.org/library/os``, would instead be redirected 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``. a Python 2 specific link such as ``http://docs.python.org/2/library/os``.
The specific subpaths which would be remapped to explicitly qualified The specific subpaths which will be redirected to explicitly qualified
paths for the Python 2 docs are: paths for the Python 2 docs are:
* ``/c-api/`` * ``/c-api/``
@ -114,7 +115,12 @@ paths for the Python 2 docs are:
* ``/py-modindex.html`` * ``/py-modindex.html``
* ``/search.html`` * ``/search.html``
The existing ``/py3k/`` subpath would be remapped to the new ``/3/`` subpath. The existing ``/py3k/`` subpath will be redirected to the new ``/3/``
subpath.
To help ensure future stability even of links to the in-development version,
the ``/dev/`` subpath will be redirected to the appropriate version specific
subpath (currently ``/3.4/``).
Presented URLs Presented URLs
@ -128,20 +134,30 @@ resolution of any aliasing and rewriting rules:
* ``http://docs.python.org/release/x.y.z/*`` * ``http://docs.python.org/release/x.y.z/*``
* ``http://docs.python.org/devguide`` * ``http://docs.python.org/devguide``
The ``/x/`` URLs mean "give me the latest documentation for this release The ``/x/`` URLs mean "give me the latest documentation for a released
series``. Differences relative to previous versions in the release series version in this release series". It will draw the documentation from the
will be available through "version added" and "version changed" markers. 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". 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 It will draw the documentation from the relevant maintenance branch in
available in the user's browser for easy copy and pasting. (Currently, source control (or the default branch for the currently in development
references to specific versions that are not the latest in their release version. It differs from the status quo in that the URLs will
series will resolve to a stable URL for a specific maintenance version in actually remain available in the user's browser for easy copy and pasting.
the "release" hierarchy, while the current latest version in the release (Currently, references to specific versions that are not the latest in their
series resolves to the release series URL. This makes it hard to get a release series will resolve to a stable URL for a specific maintenance
"latest version specific URL", since it is always necessary to construct 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). them manually).
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 Rationale
========= =========