有助于Sphinx

有很多方法可以为Sphinx做出贡献，比如提交bug报告或特性请求、编写新文档或提交新行为或修复行为的修补程序。本指南旨在说明如何开始此操作。

寻求帮助

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

带标记的堆栈溢出 python-sphinx

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

sphinx用户<sphinx-users@googlegroups.com>

用户支持邮件列表。

sphinx dev<sphinx-dev@googlegroups.com>

与发展有关的讨论的邮件列表。

#sphinx-docon irc.Libera.chat

IRC开发问题和用户支持渠道。

错误报告和功能请求

如果您遇到Sphinx的问题或对新功能有想法，请将其提交给 issue tracker 在Github上或在 sphinx-dev 邮件列表。

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

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

贡献代码

Sphinx源代码是使用Git管理的，托管在 `GitHub`_ _. 新贡献者向Sphinx提交代码的推荐方法是分叉此存储库，并在向其分叉提交更改后提交pull请求。然后，pull请求需要得到一个核心开发人员的批准，然后才能合并到主存储库中。

入门

在开始修补程序之前，我们建议检查打开的问题或打开一个新的问题，以围绕功能想法或错误开始讨论。如果您对某个问题或您的更改感到不舒服或不确定，请随时发送电子邮件至 sphinx-dev 邮件列表。

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

1. 在GitHub上创建帐户。

2. 分叉主Sphinx存储库（sphinx doc/sphinx) 使用Github接口。

3. 将分叉存储库克隆到您的计算机上。：：

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

4. 签出相应的分支。

   sphinx采用语义版本化2.0.0（参考：https://semver.org/）。

   对于保留API和特性向后兼容性的更改，它们应该包含在下一个次要版本中，使用 A.x 分支机构。：：

   git checkout A.x
   

   对于应该等到下一个主要版本的不兼容或其他实质性更改，请使用 master 分支机构。

   对于紧急发布，必须从最新的发布标签分支一个新的补丁分支（请参见 Sphinx的释放过程 细节）

5. 设置虚拟环境。

   这对于单元测试来说是不必要的，因为 tox ，但是如果你想跑步是必要的 sphinx-build 本地或运行单元测试，而无需 tox ：：

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

6. 创建新的工作分支。选择任何你喜欢的名字。:

   git checkout -b feature-xyz
   

7. 哈，哈，哈。

   将代码与测试一起编写，这些测试将显示错误已修复或功能按预期工作。

8. 为…添加一个项目符号 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。

9. 将分支中的更改推送到GitHub上的分叉存储库：

   git push origin feature-xyz
   

10. 向相应的分支机构提交分支机构的请求 (master 或 A.x ）

11. 等待核心开发人员审阅您的更改。

编码风格

为 Sphinx 编写代码时，请遵循以下指南：

• 尝试使用与项目睡觉中使用的代码样式相同的代码样式。

• 对于重要的更改，请更新 CHANGES.rst 文件。如果您的更改改变了现有行为，请对此进行记录。

• 应记录新功能。在适当的地方包括示例和用例。如果可能，包括在生成的输出中显示的示例。

• 添加新的配置变量时，请确保将其记录并更新 sphinx/cmd/quickstart.py 如果足够重要的话。

• 添加适当的单元测试。

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

ruff .
mypy sphinx/

单元测试

Sphinx 对于Python代码用 `pytest`__ ， 对于JavaScript 用 `Karma`__ 测试。

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

• 列出所有可能的目标：

  tox -av
  

• 要为特定的Python版本运行单元测试，如Python3.10：

  tox -e py310
  

• 要为特定的Python版本运行单元测试并打开弃用警告，以便在测试输出中显示它们：

  PYTHONWARNINGS=error tox -e py310
  

• 争论到 pytest 可以通过以下方式传递 tox 例如，为了运行特定测试：

  tox -e py310 tests/test_module.py::test_new_feature
  

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

pip install .[test]

要运行JavaScript测试，请使用 npm ：：

npm install
npm run test

小技巧

karma 需要Firefox二进制文件才能用作测试浏览器。

对于基于Unix的系统，可以使用以下命令指定Firefox二进制文件的路径：

FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test

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

• 对于错误修复，首先添加一个没有更改而失败的测试，并在应用之后通过。

• 需要的测试 sphinx-build 如果可能的话，运行应该集成到一个现有的测试模块中。新的测试 @with_app 然后 build_all 因为有些断言是不好的，因为 测试套件的运行时间不应超过一分钟。 .

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

Added in version 1.6: sphinx.testing 作为实验添加。

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

待处理

以下属于开发人员指南

中提供了用于测试的实用函数和最常用的夹具 sphinx.testing 。如果您是Sphinx扩展的开发人员，则可以使用pytest编写单元测试。在这个时候， sphinx.testing 将有助于您的测试实现。

如何使用由提供的Pytest夹具 sphinx.testing ? 你可以要求 'sphinx.testing.fixtures' 在测试模块中或 conftest.py 像这样的文件：

pytest_plugins = 'sphinx.testing.fixtures'

如果您想了解更详细的用法，请参阅 tests/conftest.py 及其他 test_*.py 下的文件 tests 目录。

投稿文档

提供文档需要修改在 doc/ 文件夹。要开始，您应该首先遵循以下步骤 入门 ，然后执行以下步骤以使用文档。

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

待处理

添加更广泛的文档贡献指南。

构建文档

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

sphinx-build -M html ./doc ./build/sphinx -W --keep-going

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

您还可以构建一个 live version of the documentation 您可以在浏览器中预览。它将检测更改并在您进行任何编辑时重新加载页面。要执行此操作，请运行以下命令：

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 从过渡FEX设置格式。要执行此操作，请转到 sphinx/locale 然后跑 tx pull -f -l LANG 哪里 LANG 是现有的语言标识符。跑步是一种很好的做法 python babel_runner.py update 之后，以确保 .po 文件具有规范的巴别塔格式。

调试提示

• 如果通过运行命令对代码进行更改，请在生成文档之前删除生成缓存 make clean 或使用 sphinx-build -E 选择权。

• 使用 sphinx-build -P 选择运行 pdb 例外情况。

• 使用 node.pformat() 和 node.asdom().toxml() 生成文档结构的可打印表示形式。

• 设置配置变量 keep_warnings 到 True 因此，警告将显示在生成的输出中。

• 设置配置变量 nitpicky 到 True 所以Sphinx会抱怨没有已知目标的参考文献。

• 中设置调试选项。 Docutils configuration file 。

• 中的JavaScript词干处理算法 sphinx/search/non-minified-js/*.js 使用以下工具生成 snowball 通过克隆存储库、执行 make dist_libstemmer_js 然后解压生成的tarball dist 目录。

  缩小的文件位于 sphinx/search/minified-js/*.js 从非小型化的元素生成，使用 uglifyjs (通过NPM安装)，带 -m 选项以启用损坏。