贡献Sphinx¶

有很多方法可以为 Sphinx 贡献,无论是提交 bug 报告或功能请求,编写新文档,还是为新的或修复的功能提交补丁.本指南旨在说明如何开始这项工作.

获取帮助¶

Sphinx社区维护着多个邮件列表和IRC频道.

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

错误报告和功能请求¶

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

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

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

贡献代码¶

Sphinx源代码使用Git进行管理,并且托管在 GitHub 上.推荐的新贡献者向Sphinx提交代码的方式是先fork这个仓库,然后在提交更改到自己的fork后提交一个pull request.此pull request需要得到核心开发者之一的批准,然后才能合并到主仓库中.

开始使用¶

在开始修补之前,我们建议检查是否有未解决的问题,或者打开一个新的问题来讨论一个功能想法或一个bug.如果你对某个问题或你的更改感到不安或不确定,欢迎随时开始讨论 .

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

在 GitHub 上创建账户.
使用 GitHub 界面从主 Sphinx 仓库（ sphinx-doc/sphinx ）进行分叉.

将克隆的仓库复制到您的机器上.

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 '#42: Add useful new feature that does this.'
```
GitHub 识别某些短语,可以用来自动更新问题跟踪器.例如:
```
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
```
将关闭问题 #42.
将分支中的更改推送到您在 GitHub 上的分叉存储库:
```
git push origin feature-xyz
```
从你的分支提交一个合并请求到 master 分支.
等待核心开发者或贡献者审查你的更改.

编码风格¶

请在为Sphinx编写代码时遵循以下指南:

尽量使用项目中其余部分使用的相同代码风格.
对于重要的更改,请更新 CHANGES.rst 文件.如果您的更改更改了现有行为,请对此进行记录.
新功能应进行文档记录.包括适当的例子和用例.如果可能,包含在生成的输出中显示的示例.
当添加新的配置变量时,请确保对其进行文档记录 ,并在重要时更新 sphinx/cmd/quickstart.py .
添加适当的单元测试.

样式和类型检查可以如下进行:

ruff check .
mypy

单元测试¶

Sphinx 使用 pytest 测试 Python 代码,使用 Jasmine 测试 JavaScript.

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

列出所有可能的目标:
```
tox -av
```
要运行特定Python版本（例如Python 3.12）的单元测试:
```
tox -e py312
```
可以通过 tox 向 pytest 传递参数,例如,为了运行特定的测试:
```
tox -e py312 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 夹具和 app.build() .

Added in version 1.8: Sphinx 也运行 JavaScript 测试.

在 1.5.2 版本发生变更: Sphinx从nose切换到了pytest.

贡献文档¶

为文档贡献涉及修改位于 doc/ 文件夹中的源文件.要开始,您首先应遵循开始使用 ,然后按照以下步骤与文档一起工作.

以下章节描述了如何开始贡献文档,以及我们使用的几种不同工具的关键方面.

待处理

添加更详细的文档贡献指南.

构建文档¶

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

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

这将解析Sphinx文档的源文件,并为您生成HTML以便在:file:build/sphinx/html 中预览.

您还可以构建一个**文档的实时版本**,可以在浏览器中预览.它将检测更改,并在您进行编辑时重新加载页面.要做到这一点,请运行以下命令:

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

翻译¶

Sphinx中构建的消息部分被翻译成多种语言环境.这些翻译保存在gettext .po 文件中,来源于主模板 sphinx/locale/sphinx.pot .

Sphinx使用 Babel 来提取消息并维护目录文件.:file: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 放入其中.不要忘记更新:file:doc/usage/configuration.rst 中:confval:language 的可能值.

Sphinx 核心消息也可以在 Transifex 上进行翻译.可以使用由 transifex_client Python 包提供的 tx 客户端工具从 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 配置文件中设置调试选项.

更新生成的文件¶

JavaScript 词干算法在 sphinx/search/non-minified-js/*.js 中是通过克隆 snowball 仓库生成的,执行 make dist_libstemmer_js 然后解压生成在 dist 目录中的压缩包.

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