贡献 Sphinx¶

您可以通过多种方式为 Sphinx 做出贡献，无论是提交 bug 报告或功能请求、编写新的文档，还是为新增或修复的行为提交补丁。本指南旨在说明如何开始参与贡献。

获取帮助¶

Sphinx 社区维护着许多邮件列表和 IRC 频道。

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

Bug 报告和功能请求¶

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

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

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

贡献代码¶

Sphinx 源代码使用 Git 进行管理，并托管在 GitHub 上。对于新的贡献者，向 Sphinx 提交代码的推荐方式是 fork 此仓库，并在将更改提交到您的 fork 后提交 pull request。pull request 然后需要由核心开发人员之一批准，然后才能合并到主仓库中。

开始入门¶

在开始编写补丁之前，我们建议检查是否有未解决的 issue，或者打开一个新的 issue，开始讨论关于功能想法或 bug 的问题。如果您对某个 issue 或您的更改感到不舒服或不确定，请随时发起讨论。

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

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

将 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 分支提交一个 pull request。

GitHub 识别某些短语，这些短语可用于自动更新 issue 跟踪器。例如，在 pull request 的正文中包含 ‘Closes #42’ 将在 PR 合并后关闭 issue #42。
等待核心开发人员或贡献者审查您的更改。

编码风格¶

在为 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 .[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 使用 Babel 提取消息并维护目录文件。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 放在其中。别忘了更新 language 在 doc/usage/configuration.rst 中的可能值。

Sphinx 核心消息也可以在 Transifex 上翻译。Transifex 提供的 tx 客户端工具 transifex_client Python 包可用于从 Transifex 拉取 .po 格式的翻译。为此，请转到 sphinx/locale，然后运行 tx pull -f -l LANG，其中 LANG 是现有的语言标识符。最佳实践是在之后运行 python babel_runner.py update，以确保 .po 文件具有规范的 Babel 格式。

调试技巧¶

如果您在代码中进行了更改，请在构建文档之前删除构建缓存，方法是运行命令 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 词干提取算法是使用 snowball 生成的，方法是克隆仓库，执行 make dist_libstemmer_js，然后解压缩在 dist 目录中生成的 tarball。

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