PEP 430 – 将默认在线文档迁移到 Python 3
- 作者:
- Alyssa Coghlan <ncoghlan at gmail.com>
- BDFL 委托：
- Georg Brandl
- 状态:
- 最终版
- 类型:
- 信息性
- 创建日期:
- 2012年10月27日
摘要
本PEP提出了一种策略，用于在用户访问 docs.python.org 时，将呈现给用户的Python文档的默认版本从2.7迁移到Python 3.3。
它提出了一种向后兼容的方案，该方案保留了指向Python 2文档的现有深层链接的含义，同时默认呈现Python 3文档，并以一种避免让Python 3文档看起来像二等公民的方式呈现Python 2和3文档。
背景
随着整个Python生态系统从Python 2向Python 3的过渡仍在进行中，一个定期出现的问题[1], [2]是何时以及如何处理从提供Python 2文档作为docs.python.org根URL默认显示版本到提供Python 3文档的更改。
主要顾虑
任何迁移提案都需要解决几个主要问题。
不要混淆初学者
许多初学者通过第三方资源学习Python。这些资源，并非都是在线资源，可能会引用 python.org 在线文档以获取更多背景信息和详细信息。
重要的是，即使在线文档更新了，“版本添加”和“版本更改”标签通常也提供足够的信息，让用户根据他们正在使用的特定版本进行适当调整。
虽然指向 python.org 文档的深层链接在Python 2系列中偶尔会断裂，但这种情况非常罕见。
迁移到Python 3是一个非常不同的问题。许多链接会因重命名和删除而断裂，并且Python 2系列的“版本添加”和“版本更改”信息完全缺失。
不要破坏有用的资源
有许多有用的Python资源，例如 python.org 上的邮件列表存档和 Stack Overflow 等问答网站，无论提供多少通知，这些链接都极不可能更新。
旧帖子和问题答案目前都链接到 docs.python.org，期望在非限定URL处获取Python 2文档。与Python 3相关的答案中的链接在路径组件中明确使用 /py3k/ 限定。
提案
本PEP（基于五月份最初提出的想法[3]）是 根本不迁移 Python 2 特定的深层链接，而是采用一种方案，即 docs.python.org 上呈现给用户的所有URL都适当地使用相关的发布系列进行限定。
访问根URL https://docs.pythonlang.cn 的访问者将自动重定向到 https://docs.pythonlang.cn/3/，但版本特定层次结构中更深层的链接，例如 https://docs.pythonlang.cn/library/os，将重定向到 Python 2 特定链接，例如 https://docs.pythonlang.cn/2/library/os。
将重定向到Python 2文档的显式限定路径的特定子路径是
/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
现有 /py3k/ 子路径将重定向到新的 /3/ 子路径。
呈现的URL
通过此方案，在解析任何别名和重写规则后，将向用户呈现以下URL
https://docs.pythonlang.cn/x/*https://docs.pythonlang.cn/x.y/*https://docs.pythonlang.cn/dev/*https://docs.pythonlang.cn/release/x.y.z/*https://docs.pythonlang.cn/devguide
/x/ URL 表示“给我该发布系列中已发布版本的最新文档”。它将从源代码管理中的相关维护分支（Python 2始终是2.7分支，Python 3目前是3.3分支）获取文档。相对于该发布系列早期版本的差异将通过“版本添加”和“版本更改”标记提供。
/x.y/ URL 表示“给我此发布的最新文档”。它将从源代码管理中的相关维护分支（或当前开发版本的默认分支）获取文档。它与现状的不同之处在于，URL将实际保留在用户的浏览器中，便于复制和粘贴。（目前，对特定版本而非其发布系列中最新版本的引用将解析为“release”层次结构中特定维护版本的稳定URL，而发布系列中当前的最新版本将解析为发布系列URL。这使得获取“最新版本特定URL”变得困难，因为总是需要手动构造它们）。
/dev/ URL 表示源代码管理中默认分支的文档。
/release/x.y.x/ URL 将指向这些发布的文档，与发布时完全一致。
开发者指南不特定于版本，因此保留其自己的稳定 /devguide/ URL。
基本原理
有些人希望将非限定引用切换为Python 3，以表示对Python 3的信心。这样的举动要么会破坏很多东西，要么会涉及大量工作来 避免 破坏东西。
我相信我们可以通过以下方式获得大致相同的效果，而不会破坏整个世界：
- 弃用对在线文档的非限定引用（同时承诺无限期保留此类引用的含义）
- 更新所有 python.org 和 python-dev 控制的链接以使用限定引用（不包括存档电子邮件）
- 将访问
https://docs.pythonlang.cn根目录的访问者重定向到https://docs.pythonlang.cn/3.x
最重要的是，由于此方案不改变任何现有深层链接的行为，因此可以以比可能破坏深层链接或开始将非限定链接重定向到 Python 3 的方案所需的更短的警告期来实现。该方案中唯一需要任何警告的部分是将“https://docs.pythonlang.cn/”登陆页面重定向到 Python 3.3 文档的步骤。
命名空间是一个了不起的想法——让我们做更多这样的事情。
请注意，本 PEP 中描述的方法提供了两种访问默认分支内容的方式：作为 /dev/ 或使用适当的 /x.y/ 引用。这是故意的，因为默认分支用于两个不同的目的：
- 在讨论下一个版本的即将推出的功能时提供额外信息（
/x.y/URL 是合适的） - 为开发人员提供一个稳定的目标，以访问下一个功能版本的文档，无论版本如何（
/dev/URL 是合适的）
实施
docs.python.org 上的 URL 由 python.org 基础设施团队控制，而不是通过 CPython 源存储库控制，因此本 PEP 中想法的接受和实施将由该团队决定。
参考资料
版权
本文档已置于公共领域。
来源：https://github.com/python/peps/blob/main/peps/pep-0430.rst