向Sphinx做贡献¶

有很多方法可以帮助Sphinx，可以是提交bug报告或特性请求，编写新的文档，或者为新的或固定的行为提交补丁。本指南旨在说明如何开始。

获取帮助¶

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

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

错误报告和功能请求¶

如果您遇到了Sphinx的问题，或者有了新功能的想法，请将其提交到GitHub上的 issue tracker 。

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

包含或提供指向所涉及的源文件的链接可能有助于我们解决该问题。如果可能，尝试创建一个生成错误的最小项目，并将其发布。

贡献代码¶

Sphinx源码使用Git管理，并且 hosted on GitHub。新贡献者向Sphinx提交代码的推荐方式: fork此存储库、将更改提交到fork后的仓库、提交拉取请求。拉取请求需要得到一位核心开发人员的批准，才能合并到主存储库中。

开始¶

在开始修补程序之前，我们建议检查是否有未解决的问题，或者打开一个新的问题，以开始围绕功能想法或错误进行讨论。如果您对某个问题或您的更改感到不舒服或不确定，请随时 start a discussion 。

这些是在Sphinx上开始开发所需的基本步骤。

在github上创建一个账户，
使用GitHub界面 Fork 主Sphinx存储库（sphinx-doc/sphinx）。

将fork的存储库克隆到您的计算机上。

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

安装uv并设置您的环境。

我们推荐使用 uv 进行依赖管理。使用以下命令安装它：
```
python -m pip install -U uv
```
然后，设置您的环境：
```
uv sync
```
替代方案： 如果您不想使用 uv，可以使用 pip：
```
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```
创建一个新的工作分支。选择您喜欢的任何名称。
```
git switch -c feature-xyz
```
干它，干它，干它。

编写您的代码，同时进行测试，以证明错误已修复或该功能按预期工作。
如果修复或功能不是微不足道的（指小的文档更新、拼写错误修复），请在 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 文件。如果您的更改更改了现有行为，请进行文档记录。
新功能应有文档记录。在适当的地方包含示例和用例。如果可能，包含在生成的输出中显示的示例。
添加新的配置变量时，请确保记录文档到 document it 如果它足够重要的话，
添加合适的单元测试。

样式和类型检查可以按如下方式运行：

uv run ruff check
uv run ruff format
uv run mypy

单元测试¶

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

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

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

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

uv run pytest

或者使用 pip：

python -m pip install . --group test
pytest

运行JavaScript测试，使用 npm：

npm install
npm run test

小技巧

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

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

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

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

在 1.8 版本加入: Sphinx也能运行JAVA脚本测试。

在 1.5.2 版本发生变更: Sphinx从nose换成了pytest。

为文档做贡献¶

为文档做贡献涉及到修改 doc/ 目录下的源文件。你需要按照开始的要求开始，然后按下述步骤对文档展开工作：

下面章节描述如何开始为文档做贡献，以及一些我们要用到的几个工具的关键方面。

构建文档¶

运行下述命令，以构建文档：

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

这会解析Sphinx文档的源文件并且在 build/sphinx/html 下生成html文件，供您审阅。

你也可以构建一个可以在浏览器中审阅的 实时版本的文档。它将会检查源文件的变化，每次你编辑源文件时，都会重载网页。使用 sphinx-autobuild 来运行下述命令即可：

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

翻译¶

Sphinx中参与构建的信息被翻译成若干语言(locales)。来自主模板 sphinx/locale/sphinx.pot 的信息被翻译、保存为gettext的 .po 格式的文件

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

翻译好的文本，会在新版本发布前，被维护者从Transifex拉取到Sphinx 仓库。

我们不接受通过Pull Request直接修改翻译结果文件。所以请使用 Transifex平台 来做翻译贡献。

给维护者的翻译笔记¶

transifex CLI (tx) 可以用于从 Transifex·以 .po 格式拉取翻译结果。在 sphinx/locale 下运行 tx pull -f -l LANG 即可，其中 LANG 是已支持的语言的标识符。建议接着运行 python utils/babel_runner.py update 命令，以确保 .po 文件符合 Babel 规范格式。

Sphinx 使用 Babel 来提取信息、维护消息目录文件(*.po, *.pot, *.mo)。 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 configuaration file 中设置调试选项

更新生成的文件¶

JavaScript词干提取算法在 sphinx/search/non-minified-js/*.js 中，停用词文件为 sphinx/search/_stopwords/，均为使用Snowball project、运行utils/generate_snowball.py生成。

sphinx/search/minified-js/*.js 中的压缩文件是使用 uglifyjs (通过npm安装)从未压缩的文件生成的。参见 sphinx/search/minified-js/README.rst 。
位于 tests/js/fixtures/* 目录下的 searchindex.js 文件是通过在 tests/js/roots/* 中找到的相应输入项目上使用标准Sphinx HTML构建器生成的。这些夹具提供了Sphinx JavaScript单元测试使用的测试数据，可以通过运行 utils/generate_js_fixtures.py 脚本重新生成。