PEP 430 – 将 Python 3 作为默认在线文档进行迁移
- 作者:
- Alyssa Coghlan <ncoghlan at gmail.com>
- BDFL 委托人:
- Georg Brandl
- 状态:
- 最终
- 类型:
- 信息
- 创建:
- 2012-10-27
摘要
本 PEP 提出了一种将 docs.python.org 上提供给 Python 用户的 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（基于 5 月份提出的最初想法 [3]）是不迁移 Python 2 特定的深度链接，而是采用一种方案，其中所有呈现给 docs.python.org 上用户的 URL 都使用相关发布系列进行适当限定。
访问 https://docs.pythonlang.cn 根 URL 的访问者将被自动重定向到 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 实际上将在用户的浏览器中保持可用，以便于复制和粘贴。（目前，对发布系列中不是最新版本的特定版本的引用将解析为“发布”层次结构中特定维护版本的稳定 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
最后修改: 2023-10-11 12:05:51 GMT