对 Sphinx 的贡献¶

你可以通过很多方式为 Sphinx 做贡献，无论是提交错误报告或功能请求，编写新的文档或提交新的或固定行为的补丁。本指南旨在说明你如何能开始做这些事。

获得帮助¶

Sphinx 社区保持着一些邮件列表和 IRC 频道。

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

错误报告和功能请求¶

如果你遇到了 Sphinx 的问题或有新功能的想法，请提交到 GitHub 上的 issue tracker，或在 sphinx-dev 邮件列表中讨论。

对于错误报告，请包括在构建过程中产生的输出，以及 Sphinx 在遇到未处理的异常后创建的日志文件。这个文件的位置应该显示在错误信息的最后。

包括或提供所涉及的源文件的链接可能有助于我们解决这个 issue。如果可能的话，尝试创建一个产生错误的最小项目，并张贴出来

编写代码¶

Sphinx 的源代码使用 Git 管理，托管在 GitHub。推荐新的贡献者向 Sphinx 提交代码的方式是分叉这个仓库，并在提交修改后提交一个拉动请求。然后，在合并到主仓库之前，该拉取请求需要得到核心开发人员的批准。

开始行动¶

在开始打补丁之前，我们建议检查是否有开放的 issue，或者打开一个新的 issue，围绕一个功能想法或一个错误展开讨论。如果你对某个问题或你的改动感到不舒服或不确定，请随时给 sphinx-dev 邮件列表发邮件。

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

在 GitHub 上创建账户。
使用 GitHub 接口分叉主 Sphinx 仓库（sphinx-doc/sphinx）。

克隆分叉的版本库到你的机器上。

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

查看相应的分支。

Sphinx 采用了语义化版本 2.0.0（refs: https://semver.org/）。

对于保留了向后兼容的 API 和功能的变化，它们应该包含在下一个 MINOR 版本中，使用 A.x 分支。
```
git checkout A.x
```
对于不兼容的或其他实质性的变化，应该等到下一个 MAJOR 版本，使用 master 分支。

对于紧急发布，必须从最新的发布标签中分出一个新的 PATCH 分支（详见 Sphinx’s release process）。
建立虚拟环境。

由于 tox 的存在，这对单元测试来说是不必要的，但如果你想在本地运行 sphinx-build 或在没有 tox 的帮助下运行单元测试，这是必要的
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
创建新的工作分支。选择你喜欢的任何名字。
```
git checkout -b feature-xyz
```
Hack, hack, hack.

把你的代码和测试一起写出来，表明错误得到了修复，或者功能按预期工作。
在 CHANGES 中增加一个要点，如果该修复或功能不是微不足道的（小型文档更新，错别字修复），则提交
```
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.'
```
将关闭 issue #42。
将分支中的变更推送到你在 GitHub 上的分叉存储库中
```
git push origin feature-xyz
```
从你的分支向相应的分支（master 或 A.x）提交拉动请求。
等待核心开发人员审查你的修改。

Coding style¶

Please follow these guidelines when writing code for Sphinx:

Try to use the same code style as used in the rest of the project.
For non-trivial changes, please update the CHANGES file. If your changes alter existing behavior, please document this.
New features should be documented. Include examples and use cases where appropriate. If possible, include a sample that is displayed in the generated output.
When adding a new configuration variable, be sure to document it and update sphinx/cmd/quickstart.py if it’s important enough.
Add appropriate unit tests.

Style and type checks can be run using tox:

tox -e mypy
tox -e flake8

Unit tests¶

Sphinx is tested using pytest for Python code and Karma for JavaScript.

To run Python unit tests, we recommend using tox, which provides a number of targets and allows testing against multiple different Python environments:

To list all possible targets:
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.6:
```
tox -e py36
```
To run unit tests for a specific Python version and turn on deprecation warnings on so they’re shown in the test output:
```
PYTHONWARNINGS=all tox -e py36
```
Arguments to pytest can be passed via tox, e.g. in order to run a particular test:
```
tox -e py36 tests/test_module.py::test_new_feature
```

You can also test by installing dependencies in your local environment:

pip install .[test]

To run JavaScript tests, use npm:

npm install
npm run test

New unit tests should be included in the tests directory where necessary:

For bug fixes, first add a test that fails without your changes and passes after they are applied.
Tests that need a sphinx-build run should be integrated in one of the existing test modules if possible. New tests that to @with_app and then build_all for a few assertions are not good since the test suite should not take more than a minute to run.

1.8 新版功能: Sphinx also runs JavaScript tests.

1.6 新版功能: sphinx.testing is added as a experimental.

在 1.5.2 版更改: Sphinx was switched from nose to pytest.

待处理

The below belongs in the developer guide

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 with using pytest. At this time, sphinx.testing will help your test implementation.

How to use pytest fixtures that are provided by sphinx.testing? You can require 'sphinx.testing.fixtures' in your test modules or conftest.py files like this:

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 tests directory.

Writing documentation¶

待处理

Add a more extensive documentation contribution guide.

You can build documentation using tox:

tox -e docs

Translations¶

The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext .po files translated from the master template sphinx/locale/sphinx.pot.

Sphinx uses Babel to extract messages and maintain the catalog files. It is integrated in setup.py:

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

When an updated .po file is submitted, run compile_catalog to commit both the source and the compiled catalogs.

When a new locale is submitted, add a new directory with the ISO 639-1 language identifier and put sphinx.po in there. Don’t forget to update the possible values for language in doc/usage/configuration.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 setup.py update_catalog afterwards to make sure the .po file has the canonical Babel formatting.

Debugging tips¶

Delete the build cache before building documents if you make changes in the code by running the command make clean or using the sphinx-build -E option.
Use the sphinx-build -P option to run pdb on exceptions.
Use node.pformat() and node.asdom().toxml() to generate a printable representation of the document structure.
Set the configuration variable keep_warnings to True so warnings will be displayed in the generated output.
Set the configuration variable nitpicky to True so that Sphinx will complain about references without a known target.
Set the debugging options in the Docutils configuration file.
JavaScript stemming algorithms in sphinx/search/*.py (except en.py) are generated by this modified snowballcode generator. Generated JSX files are in this repository. You can get the resulting JavaScript files using the following command:
```
npm install
node_modules/.bin/grunt build # -> dest/*.global.js
```

目录

上一个主题

下一个主题

本页