为本指南做出贡献#

Python 打包用户指南欢迎贡献者！有很多方法可以提供帮助，包括

  • 阅读指南并提供反馈

  • 审阅新贡献

  • 修改现有内容

  • 编写新内容

  • 翻译指南

Python 打包用户指南的大部分工作在 项目的 GitHub 存储库 中进行。要开始，请查看 未解决的问题 和 拉取请求 的列表。如果您计划编写或编辑指南，请阅读 风格指南。

通过为 Python 打包用户指南做出贡献，您应该遵守 PSF 的 行为准则。

文档类型#

此项目由四种具有特定目的的不同文档类型组成。该项目渴望遵循 Diátaxis 流程 来创建高质量的文档。在提出对项目的补充建议时，请选择适当的文档类型。

教程#

教程专注于通过实现目标来向读者教授新概念。它们是有观点的分步指南。它们不包含无关的警告或信息。 示例教程风格文档。

指南#

指南专注于完成一项特定任务，并且可以假设具有一定程度的先决知识。这些指南类似于教程，但重点狭窄且明确，并且可以根据需要提供大量注意事项和附加信息。它们还可以讨论完成任务的多种方法。 示例指南风格文档。

讨论#

讨论专注于理解和信息。这些讨论探讨特定主题，而没有具体目标。 示例讨论风格文档。

规范#

规范是参考文档，专注于全面记录包装工具之间互操作性的商定接口。 示例规范风格文档。

翻译#

我们使用 Weblate 来管理此项目的翻译。请访问 Weblate 上的 packaging.python.org 项目来做出贡献。

如果您在翻译过程中遇到问题，请在 GitHub 上提交问题。

提示

此项目的任何翻译都应遵循 reStructuredText 语法。

添加语言#

如果您的语言未在 packaging.python.org 上列出，请单击语言列表底部的 开始新翻译 按钮并添加您要翻译的语言。

遵循 reStructuredText 语法#

如果您不熟悉 reStructuredText (RST) 语法，请在 Weblate 上翻译之前阅读本指南。

不要直接翻译参考中的文本

翻译参考中的文本时，请不要直接翻译。

错误：直接翻译以下文本
`some ref`_ -> `TRANSLATED TEXT HERE`_
正确：用您自己的语言翻译以下文本，并添加原始参考
`some ref`_ -> `TRANSLATED TEXT HERE <some ref>`_

本地构建指南#

虽然不需要做出贡献，但本地构建此指南可能有助于测试您的更改。要本地构建此指南，您需要

  1. Nox。您可以使用pip安装或升级 nox

    python -m pip install --user nox

  2. Python 3.11。我们的构建脚本通常只使用 Python 3.11 进行测试。请参阅Python 安装说明，在您的操作系统上安装 Python 3.11。

要构建指南，请在项目的根文件夹中运行以下 shell 命令

nox -s build

进程完成后，您可以在./build/html目录中找到 HTML 输出。您可以打开index.html文件，在 Web 浏览器中查看指南，但建议使用 HTTP 服务器提供指南。

您可以使用以下命令构建指南并通过 HTTP 服务器提供指南

nox -s preview

可以通过http://localhost:8000浏览指南。

指南部署的位置#

指南通过 ReadTheDocs 部署，配置位于https://readthedocs.org/projects/python-packaging-user-guide/。它由自定义域提供，并由 Fast.ly 提供前端。

风格指南#

此风格指南提供了有关如何编写 Python 打包用户指南的建议。在开始编写之前，请审阅它。通过遵循风格指南，您的贡献将有助于形成一个有凝聚力的整体，并使您的贡献更容易被项目接受。

目的#

Python 打包用户指南的目的是成为使用当前工具打包、发布和安装 Python 项目的权威资源。

范围#

本指南旨在通过准确且有针对性的建议来回答问题和解决问题。

本指南并非旨在全面，也并非旨在取代各个项目的文档。例如，pip 有几十个命令、选项和设置。pip 文档详细描述了其中的每一个，而本指南只描述了完成本指南中描述的特定任务所需的 pip 部分。

受众#

本指南的受众是任何使用 Python 和软件包的人。

不要忘记 Python 社区是庞大而友好的。读者可能与您在年龄、性别、教育、文化等方面不同，但他们同样有权了解打包。

特别是，请记住，并非所有使用 Python 的人都认为自己是程序员。本指南的受众包括天文学家、画家或学生，以及专业软件开发人员。

语调#

在编写本指南时，即使您掌握了所有答案，也要努力用一种平易近人且谦逊的语调来写。

想象一下，您正在与您知道聪明且熟练的人一起从事一个 Python 项目。您喜欢与他们合作，他们也喜欢与您合作。那个人向您提出了一个问题，您知道答案。您如何回答？这就是您应该编写本指南的方式。

以下是一项快速检查：尝试朗读以了解您的写作的语调和语气。听起来像您会说的话，还是听起来像您在扮演角色或发表演讲？随意使用缩略语，不必担心坚持繁琐的语法规则。如果您想用介词结束句子，您在此被允许这样做。

在撰写指南时，根据主题的严肃性和难度调整您的语气。如果您正在撰写入门教程，可以讲笑话，但如果您正在介绍敏感的安全建议，您可能希望完全避免讲笑话。

惯例和机制#

写给读者

在提供建议或采取步骤时，以您称呼读者或使用命令式语气。

错误：要安装它，用户运行...
正确：您可以通过运行来安装它...
正确：要安装它，运行...
陈述假设

避免做出未说明的假设。在网络上阅读意味着指南的任何页面都可能是读者首次看到的指南页面。如果您要做出假设，那么请说出您要做出哪些假设。

慷慨地交叉引用

当您第一次提到某个工具或做法时，请链接到指南中涵盖该工具或做法的部分，或链接到其他地方的相关文档。为读者节省搜索时间。

尊重命名惯例

在命名工具、站点、人员和其他专有名词时，请使用它们首选的大写形式。

错误：Pip 使用...
正确：pip 使用...

错误：...托管在 github 上。
正确：...托管在 GitHub 上。
使用性别中立的风格

通常，您会直接用您、您的和您的来称呼读者。否则，请使用性别中立的人称代词他们、他们的和他们的，或完全避免使用人称代词。

错误：维护人员上传文件。然后他...
正确：维护人员上传文件。然后他们...
正确：维护人员上传文件。然后维护人员...
标题

撰写使用读者正在搜索的单词的标题。实现此目的的一个好方法是让您的标题完成一个隐含的问题。例如，读者可能想知道如何安装 MyLibrary？因此，一个好的标题可能是安装 MyLibrary。

在章节标题中，使用句子大小写。换句话说，像您撰写典型句子一样撰写标题。

错误：您应该了解 Python 的内容
正确：您应该了解 Python 的内容
数字

在正文中，将一到九的数字写成单词。对于表中的其他数字或数字，请使用数字。