对Sphinx的贡献¶

您可以通过多种方式为Sphinx做出贡献，无论是提交错误报告或特性请求、编写新文档还是为新的或已修复的行为提交补丁。本指南用于说明如何开始使用它。

寻求帮助¶

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

带有标记的堆栈溢出 python-sphinx: 关于使用和开发的问答。
GitHub Discussions Q&A __: 问答式讨论论坛。
Sphinx-用户<Sphinx-用户@googlegroups.com>: 用于用户支持的邮件列表。
Sphinx-dev<sphinx-dev@googlegroups.com>: 与开发相关的讨论的邮件列表。
#sphinx-docon irc.Libera.chat: IRC发展问题和用户支持频道。

错误报告和功能请求¶

如果您遇到Sphinx问题或对新功能有想法，请将其提交至 issue tracker 在GitHub上

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

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

贡献代码¶

Sphinx源代码使用Git管理，并且是 hosted on GitHub . 新贡献者向Sphinx提交代码的推荐方法是对此存储库进行分叉，并在提交对其分叉的更改后提交拉取请求。然后，拉取请求在合并到主存储库之前需要得到核心开发人员之一的批准。

快速入门¶

在开始使用补丁之前，我们建议检查未解决的问题或打开新问题以开始围绕功能想法或错误的讨论。如果您对某个问题或您的更改感到不舒服或不确定，请随时 start a discussion .

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

在GitHub上创建帐户。
Fork 主要的Sphinx存储库 (sphinx-doc/sphinx) 使用GitHub接口。

将分叉存储库克隆到您的机器。

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
```
砍，砍，砍。

编写代码的同时，还要进行测试，以证明错误已修复或功能按预期工作。
添加要点 CHANGES.rst 如果修复或功能并非微不足道（小文档更新、拼写错误修复），则提交：
```
git commit -m 'Add useful new feature that does this.'
```
将分支中的更改推送到GitHub上的分叉存储库：
```
git push origin feature-xyz
```
从您的分支向 master 分公司

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

编码风格¶

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

尝试使用与项目其余部分相同的代码样式。
对于非平凡的更改，请更新 CHANGES.rst 文件.如果您的更改改变了现有行为，请记录此内容。
应记录新功能。适当时包括示例和用例。如果可能的话，请包括在生成的输出中显示的示例。
添加新配置变量时，请务必 document it 和更新 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系统上，您可以检查 firefox 通过运行命令行中的二进制 command -v firefox .

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

对于错误修复，首先添加一个测试，该测试在没有您的更改的情况下失败，并在应用更改后通过。
需要进行的测试 sphinx-build 如果可能的话，应将运行集成到现有的测试模块之一中。
测试应该快速并且仅测试相关组件，因为我们的目标是 the test suite should not take more than a minute to run .一般来说，避免使用 app 夹具和 app.build() 除非需要完整的集成测试。

Added in version 1.8: Sphinx还运行JavaScript测试。

在 1.5.2 版本发生变更: Sphinx从鼻子换成了最火爆的。

投稿文档¶

为文档做出贡献涉及修改中找到的源文件 doc/ 文件夹.要开始，您应该首先关注快速入门，然后采取以下步骤处理文档。

以下各节描述如何开始使用贡献文档，以及我们使用的几个不同工具的关键方面。

待处理

添加更广泛的文档投稿指南。

构建文档¶

要生成文档，请运行以下命令：

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

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

您还可以建立一个 live version of the documentation 您可以在浏览器中预览。它将检测更改并在您进行编辑时重新加载页面。为此，请使用 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 . 那里 tx 客户端工具，该工具由 transifex_client Python包，可以用来拉入翻译 .po 格式来自Transifex。要做到这一点，请转到 sphinx/locale 然后运行 tx pull -f -l LANG 哪里 LANG 是现有的语言标识符。跑步是很好的练习 python babel_runner.py update 之后以确保 .po 文件具有规范的巴别塔格式。

调试提示¶

如果通过运行命令对代码进行更改，请在生成文档之前删除生成缓存 make clean 或使用 sphinx-build --fresh-env 选项.
使用 sphinx-build --pdb 选项来运行 pdb 关于例外。
使用 node.pformat() 和 node.asdom().toxml() 以生成文档结构的可打印表示。
设置配置变量 keep_warnings 至 True 因此，警告将显示在生成的输出中。
设置配置变量 nitpicky 至 True 这样Sphinx就会抱怨没有已知目标的引用。
中设置调试选项。 Docutils configuration file 。

更新生成的文件¶

JavaScript词干算法 sphinx/search/non-minified-js/*.js 和stopword文件 sphinx/search/_stopwords/ 产生自本 Snowball project 通过运行 utils/generate_snowball.py .

缩小的文件 sphinx/search/minified-js/*.js 使用非缩小化的生成 uglifyjs （通过nPM安装）。看到 sphinx/search/minified-js/README.rst .
的 searchindex.js 中找到的文件 tests/js/fixtures/* 目录是通过在中找到的相应输入项目上使用标准Sphinx HTML构建器生成的 tests/js/roots/* .这些装置提供Sphinx JavaScript单元测试使用的测试数据，并且可以通过运行 utils/generate_js_fixtures.py 剧本