对sphinx的贡献¶

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

Get help¶

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

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

错误报告和功能请求¶

如果您在使用Sphinx时遇到问题或有新功能的想法，请将其提交到GitHub上的“issue tracker”或在“Sphinx dev”邮件列表中讨论。

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

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

Contribute code¶

Sphinx源代码使用Git进行管理，并托管在“GitHub”上。新贡献者向Sphinx提交代码的推荐方法是fork这个存储库，并在提交对fork的更改后提交pull请求。然后，在将pull请求合并到主存储库之前，它需要得到一个核心开发人员的批准。

开始¶

在开始修补程序之前，我们建议您检查是否存在未解决的问题或打开一个新的问题，以便围绕某个功能理念或某个bug展开讨论。如果您对某个问题或您的更改感到不安或不确定，请随时发送电子邮件至*sphinx dev*邮件列表。

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

在github上创建一个账户，
Sphinx存储库（`Sphinx doc/Sphinx<https://github.com/sphinx-doc/sphinx>`_)使用GitHub接口。

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

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

检查合适的分支。

Sphinx采用语义版本控制2.0.0（参考文献：https://semver.org/).

对于保留API和特性向后兼容性的更改，它们应该包含在下一个次要版本中，请使用“A.x”分支。:
```
git checkout A.x
```
对于应该等到下一个主要版本的不兼容或其他实质性更改，请使用“master”分支。

对于紧急发布，必须从最新的release标记分支一个新的补丁分支（参见：doc:`release process`了解详细信息）。
建立一个虚拟环境。

由于“tox”，这对于单元测试来说不是必需的，但是如果您希望在本地运行“sphinx build”或在没有“tox”帮助的情况下运行单元测试，那么这是必需的：
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
创建新的工作分支。选择你喜欢的名字。:
```
git checkout -b feature-xyz
```
黑客，黑客，黑客。

编写您的代码，同时进行测试，以证明错误已修复或该功能按预期工作。
Add a bullet point to CHANGES.rst if the fix or feature is not trivial (small doc updates, typo fixes), then commit:
```
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”或“a.x”）提交请求。
等待核心开发人员检查您的更改。

代码样式¶

编写sphinx代码时请遵循以下准则：

代码风格尽量与项目的其他部分相同。
For non-trivial changes, please update the CHANGES.rst file. If your changes alter existing behavior, please document this.
新特性应记录在案。包括适当的例子和用例。如果可能，包括在生成的输出中显示的示例。
添加新的配置变量时，请确保对其进行记录并更新：file:sphinx/cmd/快速入门.py，如果它足够重要的话。
添加合适的单元测试。

Style and type checks can be run as follows:

ruff .
mypy sphinx/

单元测试¶

Sphinx在Python代码中使用“pytest”进行测试，JavaScript使用“Karma”测试。

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

列出所有可能的目标：
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.10:
```
tox -e py310
```
To run unit tests for a specific Python version and turn on deprecation warnings so they’re shown in the test output:
```
PYTHONWARNINGS=error tox -e py310
```
Arguments to pytest can be passed via tox, e.g., in order to run a particular test:
```
tox -e py310 tests/test_module.py::test_new_feature
```

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

pip install .[test]

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

npm install
npm run test

小技巧

karma requires a Firefox binary to use as a test browser.

For Unix-based systems, you can specify the path to the Firefox binary using:

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

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

对于bug修复，首先添加一个测试，该测试在没有更改的情况下失败，并在应用更改后通过。
如果可能，需要“sphinx build”运行的测试应该集成到一个现有的测试模块中。对于一些断言，新的测试先是“使用”app“@”，然后是“buildu all”，这是不好的，因为*测试套件的运行时间不应超过一分钟*。

Added in version 1.8: Sphinx也能运行JAVA脚本测试。

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

在 1.5.2 版本发生变更: sphinx从nose换成了py测试。

待处理

以下内容属于开发人员指南

Utility functions and pytest fixtures for testing are provided in sphinx.testing. If you are a developer of Sphinx extensions, you can write unit tests by using pytest. At this time, sphinx.testing will help your test implementation.

如何使用由提供的pytest设备``sphinx.testing``? 你可以要求`’sphinx.testing’``在你的测试模块中，或者``conftest.py``像这样的文件：

pytest_plugins = 'sphinx.testing.fixtures'

If you want to know more detailed usage, please refer to tests/conftest.py and other test_*.py files under the tests directory.

Contribute documentation¶

Contributing to documentation involves modifying the source files found in the doc/ folder. To get started, you should first follow 开始, and then take the steps below to work with the documentation.

The following sections describe how to get started with contributing documentation, as well as key aspects of a few different tools that we use.

待处理

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

Build the documentation¶

To build the documentation, run the following command:

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

This will parse the Sphinx documentation’s source files and generate HTML for you to preview in build/sphinx/html.

You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, run the following command:

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

翻译¶

Sphinx中进入构建的消息部分被转换成几个区域设置。翻译保存为从主模板file:sphinx/locale翻译的gettext``.po``文件/shinx.pot`.

Sphinx uses Babel to extract messages and maintain the catalog files. The utils directory contains a helper script, babel_runner.py.

Use python babel_runner.py extract to update the .pot template.
Use python babel_runner.py update to update all existing language catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in the template file.
Use python babel_runner.py compile to compile the .po files to binary .mo files and .js files.

When an updated .po file is submitted, run python babel_runner.py compile to commit both the source and the compiled catalogs.

当提交一个新的语言环境时，添加一个带有ISO639-1语言标识符的新目录，并将``sphinx.po``在那里。别忘了更新“doc/usage”中的confval:language`的可能值/配置.rst`.

The Sphinx core messages can also be translated on Transifex. There tx client tool, which is provided by the transifex_client Python package, can be used to pull translations in .po format from Transifex. To do this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is an existing language identifier. It is good practice to run python babel_runner.py update afterwards to make sure the .po file has the canonical Babel formatting.

调试小贴士¶

如果通过运行命令“make clean”或使用：option:`sphinx build-E`选项对代码进行更改，请在生成文档之前删除生成缓存。
使用：选项：`sphinx build-P`选项对异常运行“pdb”。
使用``节点.pformat（）``和``节点.asdom（）.toxml（）``生成文档结构的可打印表示。
将配置变量confval:keepu warnings设置为True，这样生成的输出中将显示警告。
将配置变量confval:nitpicky设置为True，这样Sphinx就会抱怨没有已知目标的引用。
在`Docutils配置文件中设置调试选项 <https://docutils.sourceforge.io/docs/user/config.html>`_。
JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js are generated using snowball by cloning the repository, executing make dist_libstemmer_js and then unpacking the tarball which is generated in dist directory.

Minified files in sphinx/search/minified-js/*.js are generated from non-minified ones using uglifyjs (installed via npm), with -m option to enable mangling.

Sphinx

On this page

Site navigation