贡献给 Sphinx¶

有许多方式可以为 Sphinx 贡献，无论是提交 Bug 报告或功能请求，编写新文档，还是提交新功能或修复行为的补丁。本指南旨在说明如何开始这些工作。

获取帮助¶

Sphinx 社区维护着一些邮件列表和 IRC 频道。

Stack Overflow，标签为 python-sphinx: 关于使用和开发的问题与答案。
GitHub Discussions 问答: 问答式论坛，用于讨论。
sphinx-users <sphinx-users@googlegroups.com>: 用户支持邮件列表。
sphinx-dev <sphinx-dev@googlegroups.com>: 与开发相关的讨论邮件列表。
irc.libera.chat 上的 #sphinx-doc: 用于开发问题和用户支持的 IRC 频道。

错误报告和功能请求¶

如果您在使用 Sphinx 时遇到问题或有新功能的想法，请将其提交到 GitHub 上的问题跟踪器。

对于错误报告，请包含构建过程中产生的输出以及 Sphinx 在遇到未处理异常后创建的日志文件。此文件的位置应显示在错误消息的末尾。请同时包含 sphinx-build --bug-report 的输出。

包含或提供相关源文件的链接可能有助于我们解决问题。如果可能，请尝试创建一个能重现错误的最小项目并发布它。

贡献代码¶

Sphinx 源代码使用 Git 管理，并托管在 GitHub 上。推荐新贡献者向 Sphinx 提交代码的方式是 Fork 这个仓库，并在提交更改到其 Fork 后提交拉取请求。拉取请求需要经过核心开发人员之一的批准，才能合并到主仓库。

入门¶

在开始打补丁之前，我们建议检查开放问题或开启新问题，以围绕功能想法或 Bug 展开讨论。如果您对某个问题或您的更改感到不适或不确定，请随时开始讨论。

以下是开始在 Sphinx 上进行开发所需的基本步骤。

在 GitHub 上创建一个账户。
使用 GitHub 界面Fork 主 Sphinx 仓库 (sphinx-doc/sphinx)。

将 Fork 的仓库克隆到您的机器。

git clone https://github.com/<USERNAME>/sphinx
cd sphinx

设置一个虚拟环境。

由于 tox 的存在，这对于单元测试来说不是必需的，但如果您希望在本地运行 sphinx-build 或在没有 tox 帮助的情况下运行单元测试，则是必需的。
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
创建一个新的工作分支。选择您喜欢的任何名称。
```
git switch -c feature-xyz
```
编码，编码，编码。

编写您的代码以及测试，以证明 Bug 已修复或功能按预期工作。
如果修复或功能不是微不足道的（小的文档更新、拼写错误修复），请在 CHANGES.rst 中添加一个项目符号，然后提交。
```
git commit -m 'Add useful new feature that does this.'
```
将分支中的更改推送到您在 GitHub 上的 Fork 仓库。
```
git push origin feature-xyz
```
从您的分支向 master 分支提交拉取请求。

GitHub 识别某些短语，这些短语可用于自动更新问题跟踪器。例如，在拉取请求的正文中包含“Closes #42”将在 PR 合并时关闭问题 #42。
等待核心开发人员或贡献者审查您的更改。

您可能会被要求处理审查意见。如果是这样，请避免强制推送到分支。Sphinx 在合并 PR 时使用 *squash merge* 策略，因此后续提交都将合并在一起。

代码风格¶

为 Sphinx 编写代码时，请遵循以下准则

尝试使用与项目其余部分相同的代码风格。
对于非微不足道的更改，请更新 CHANGES.rst 文件。如果您的更改改变了现有行为，请记录下来。
新功能应该有文档。在适当的情况下包含示例和用例。如果可能，包含一个在生成输出中显示的示例。
添加新的配置变量时，请务必对其进行文档化，如果足够重要，请更新 sphinx/cmd/quickstart.py。
添加适当的单元测试。

风格和类型检查可以按如下方式运行

ruff check .
mypy

单元测试¶

Sphinx 使用 pytest 进行 Python 代码测试，使用 Jasmine 进行 JavaScript 测试。

要运行 Python 单元测试，我们建议使用 tox，它提供了许多目标并允许针对多个不同的 Python 环境进行测试。

列出所有可能的目标
```
tox -av
```
要运行特定 Python 版本（如 Python 3.13）的单元测试
```
tox -e py313
```
pytest 的参数可以通过 tox 传递，例如，为了运行特定的测试
```
tox -e py313 tests/test_module.py::test_new_feature
```

您也可以通过在本地环境中安装依赖项来进行测试

pip install . --group test

要运行 JavaScript 测试，请使用 npm

npm install
npm run test

提示

jasmine 需要一个 Firefox 二进制文件作为测试浏览器。

在 Unix 系统上，您可以通过运行 command -v firefox 在命令行检查 firefox 二进制文件的存在和位置。

新的单元测试应在必要时包含在 tests/ 目录中。

对于 Bug 修复，首先添加一个在没有您的更改时失败，并在应用后通过的测试。
需要运行 sphinx-build 的测试如果可能，应集成到现有的测试模块中。
测试应该快速且只测试相关组件，因为我们的目标是 *测试套件运行时间不应超过一分钟*。通常，除非需要完整的集成测试，否则避免使用 app fixture 和 app.build()。

1.8 版本新增：Sphinx 也运行 JavaScript 测试。

1.5.2 版本更改：Sphinx 从 nose 切换到 pytest。

贡献文档¶

贡献文档涉及修改 doc/ 文件夹中的源文件。要开始，您应该首先遵循入门，然后按照以下步骤处理文档。

以下部分描述了如何开始贡献文档，以及我们使用的一些不同工具的关键方面。

构建文档¶

要构建文档，请运行以下命令

sphinx-build -M html ./doc ./build/sphinx --fail-on-warning

这将解析 Sphinx 文档的源文件并生成 HTML，供您在 build/sphinx/html 中预览。

您还可以构建一个**实时版本**的文档，可以在浏览器中预览。它将检测更改并在您进行任何编辑时重新加载页面。为此，请使用 sphinx-autobuild 运行以下命令

sphinx-autobuild ./doc ./build/sphinx/

翻译¶

Sphinx 中进入构建过程的消息部分已翻译成多种语言环境。翻译保存在 gettext .po 文件中，这些文件从主模板 sphinx/locale/sphinx.pot 翻译而来。

这些 Sphinx 核心消息使用在线 Transifex 平台进行翻译。

在发布新版本之前，维护者会从平台将翻译好的字符串拉取到 Sphinx 仓库中。

我们不接受直接更改翻译文件的拉取请求。相反，请通过 Transifex 平台贡献翻译。

维护者翻译须知¶

transifex CLI (tx) 可用于从 Transifex 以 .po 格式拉取翻译。为此，请进入 sphinx/locale，然后运行 tx pull -f -l LANG，其中 LANG 是一个现有的语言标识符。之后运行 python utils/babel_runner.py update 是一个好习惯，以确保 .po 文件具有规范的 Babel 格式。

Sphinx 使用 Babel 提取消息并维护目录文件。utils 目录包含一个辅助脚本，utils/babel_runner.py。

使用 python babel_runner.py extract 更新 .pot 模板。
使用 python babel_runner.py update 使用模板文件中的当前消息更新 sphinx/locale/*/LC_MESSAGES 中所有现有语言目录。
使用 python babel_runner.py compile 将 .po 文件编译为二进制 .mo 文件和 .js 文件。

当提交更新的 .po 文件时，运行 python babel_runner.py compile 以提交源和编译后的目录。

添加新语言环境时，添加一个带有 ISO 639-1 语言标识符的新目录，并在其中放置 sphinx.po。不要忘记更新 doc/usage/configuration.rst 中 language 的可能值。

调试技巧¶

如果您在代码中进行更改，请在构建文档之前通过运行命令 make clean 或使用 sphinx-build --fresh-env 选项删除构建缓存。
使用 sphinx-build --pdb 选项在异常时运行 pdb。
使用 node.pformat() 和 node.asdom().toxml() 生成文档结构的可打印表示。
将配置变量 keep_warnings 设置为 True，以便警告将显示在生成的输出中。
将配置变量 nitpicky 设置为 True，以便 Sphinx 会对没有已知目标的引用发出抱怨。
在 Docutils 配置文件中设置调试选项。

更新生成的文件¶

sphinx/search/non-minified-js/*.js 中的 JavaScript 词干提取算法和 sphinx/search/_stopwords/ 中的停用词文件由运行 utils/generate_snowball.py 从 Snowball 项目生成。

sphinx/search/minified-js/*.js 中的压缩文件使用 uglifyjs（通过 npm 安装）从非压缩文件生成。请参阅 sphinx/search/minified-js/README.rst。
tests/js/fixtures/* 目录中的 searchindex.js 文件通过在 tests/js/roots/* 中找到的相应输入项目上使用标准 Sphinx HTML 构建器生成。这些 fixture 提供了 Sphinx JavaScript 单元测试所使用的测试数据，并且可以通过运行 utils/generate_js_fixtures.py 脚本重新生成。