参与到 Sphinx

你可以通过很多方式参与到 Sphinx，比如提交缺陷报告或功能请求、编写新文档或提交针对新行为或修复行为的补丁程序。此指南可以帮助你开始参与。

获取帮助

Sphinx 社区维护了大量邮件列表和 IRC 频道。

带有标签 python-sphinx 的 Stack Overflow

有关使用和开发的问题和答案。

GitHub 讨论区问答

讨论用的问答式论坛。

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 后提交一个拉取请求。然后，在将拉取请求合并到主存储库之前，需要得到核心开发人员之一的批准。

开始

在开始进行补丁之前，我们建议检查是否有开放的问题，或者创建一个新的问题，以开始讨论功能想法或错误。如果你对某个问题或你的更改感到不舒服或不确定，请随时发起讨论。

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

  1. 在 GitHub 上创建一个帐户。

  2. 使用 GitHub 界面Fork主 Sphinx 存储库 (sphinx-doc/sphinx)。

  3. 克隆已 Fork 的存储库到你的计算机。

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

  4. 设置一个虚拟环境。

    由于有tox，单元测试不需要这样做，但如果你希望在本地运行sphinx-build或在没有tox帮助的情况下运行单元测试，则需要这样做

    virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .

  5. 创建一个新的工作分支。选择你喜欢的任何名称。

    git switch -c feature-xyz

  6. 反复修改。

    编写代码以及显示错误已修复或功能按预期工作的测试。

  7. 如果修复或功能不是微不足道的（小的文档更新、拼写错误修复），则在 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。

  8. 将分支中的更改推送到 GitHub 上你已 Fork 的存储库

    git push origin feature-xyz

  9. 从你的分支向 master 分支提交一个拉取请求。

  10. 等待核心开发人员或贡献者审查你的更改。

编码风格

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

  • 请尝试使用与项目其余部分相同的代码风格。

  • 对于非琐碎的变更，请更新 CHANGES.rst 文件。如果你的变更改变了现有行为，请记录这一点。

  • 新的特性应该记录下来。在适当的地方包含示例和用例。如果可能，包含一个显示在生成输出中的示例。

  • 添加新的配置变量时，务必 记录下来，如果足够重要，请更新 sphinx/cmd/quickstart.py。

  • 添加适当的单元测试。

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

ruff check .
mypy

单元测试

对于 Python 代码，使用 pytest 来测试 Sphinx；对于 JavaScript 代码，使用 Jasmine 来测试 Sphinx。

我们建议使用 tox 来运行 Python 单元测试，它提供了许多目标，并允许针对多个不同的 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]

使用 npm 来运行 JavaScript 测试

npm install
npm run test

提示

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

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

如有必要，应该将新的单元测试包含在 tests/ 目录中

  • 对于 bug 修复，首先添加一个在没有你的变更时失败，在应用变更后通过的测试。

  • 可能的话，应该将需要运行 sphinx-build 的测试集成到现有的测试模块中。

  • 测试应该很快，并且只测试相关的组件，因为我们的目标是整个测试套件的运行时间不应超过一分钟。一般来说，除非需要完整的集成测试，否则避免使用 app 夹具和 app.build()。

在 1.8 版本中添加： Sphinx 还运行 JavaScript 测试。

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

贡献文档

参与文档编写涉及修改 doc/ 文件夹中的源文件。要开始，您应该首先按照 入门 进行操作，然后执行以下步骤来处理文档。

以下几节介绍了参与文档编写的入门方法，以及我们使用的几种不同工具的关键方面。

构建文档

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

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

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

您还可以构建一个文档实时版本，以便在浏览器中预览。无论何时编辑，它都将检测到更改并重新加载页面。要做到这一点，请运行以下命令

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。不要忘记在 doc/usage/configuration.rst 中更新 language 可选值。

Sphinx 核心信息也可以在 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 配置文件 中设置调试选项。

更新生成的文件

  • 使用 snowball 生成 sphinx/search/non-minified-js/*.js 中的 JavaScript 词干算法，通过克隆存储库，执行 make dist_libstemmer_js，然后解压在 dist 目录中生成的任务包。

    使用 uglifyjs（通过 npm 安装）从 sphinx/search/minified-js/*.js 中的非压缩文件生成压缩文件，其中 -m 选项用于启用混淆。

  • searchindex.js 文件位于 tests/js/fixtures/* 目录中，是使用标准 Sphinx HTML 生成器在 tests/js/roots/* 中找到的相应输入项目上生成的。固定装置提供了 Sphinx JavaScript 单元测试使用的数据，并且可以通过运行 utils/generate_js_fixtures.py 脚本来重新生成。