貢獻 Sphinx¶

There are many ways you can contribute to Sphinx, be it filing bug reports or feature requests, writing new documentation or submitting patches for new or fixed behavior. This guide serves to illustrate how you can get started with this.

Get help¶

The Sphinx community maintains a number of mailing lists and IRC channels.

Stack Overflow with tag python-sphinx: Questions and answers about use and development.
GitHub Discussions Q&A: Question-and-answer style forum for discussions.
sphinx-users <sphinx-users@googlegroups.com>: Mailing list for user support.
sphinx-dev <sphinx-dev@googlegroups.com>: Mailing list for development related discussions.
#sphinx-doc on irc.libera.chat: IRC channel for development questions and user support.

臭蟲回報與功能請求¶

If you have encountered a problem with Sphinx or have an idea for a new feature, please submit it to the issue tracker on GitHub.

For bug reports, please include the output produced during the build process and also the log file Sphinx creates after it encounters an unhandled exception. The location of this file should be shown towards the end of the error message. Please also include the output of sphinx-build --bug-report.

Including or providing a link to the source files involved may help us fix the issue. If possible, try to create a minimal project that produces the error and post that instead.

貢獻程式碼¶

The Sphinx source code is managed using Git and is hosted on GitHub. The recommended way for new contributors to submit code to Sphinx is to fork this repository and submit a pull request after committing changes to their fork. The pull request will then need to be approved by one of the core developers before it is merged into the main repository.

開始使用¶

Before starting on a patch, we recommend checking for open issues or opening a fresh issue to start a discussion around a feature idea or a bug. If you feel uncomfortable or uncertain about an issue or your changes, feel free to start a discussion.

These are the basic steps needed to start developing on Sphinx.

在 GitHub 上建立帳號。
Fork the main Sphinx repository (sphinx-doc/sphinx) using the GitHub interface.

Clone the forked repository to your machine.

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

Install uv and set up your environment.

We recommend using uv for dependency management. Install it with:
```
python -m pip install -U uv
```
Then, set up your environment:
```
uv sync
```
Alternative: If you prefer not to use uv, you can use pip:
```
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```
建立一個新的工作分支。選擇任何你喜歡的名稱。
```
git switch -c feature-xyz
```
Hack, hack, hack.

Write your code along with tests that shows that the bug was fixed or that the feature works as expected.
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 'Add useful new feature that does this.'
```
將分支中的變更推送到您在 GitHub 上分叉的儲存庫：
```
git push origin feature-xyz
```
從您的分支提交一個拉取請求到 master 分支。

GitHub 會自動識別某些用於更新議題追蹤器的特定短語。舉例來說，若在拉取請求的內容中包含「Closes #42」，當該 PR 被合併時，將會關閉編號為 #42 的議題。
等待核心開發者或貢獻者審核您的變更。

You may be asked to address comments on the review. If so, please avoid force pushing to the branch. Sphinx uses the squash merge strategy when merging PRs, so follow-up commits will all be combined.

編碼風格¶

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.rst 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.
增添合適的單元測試。

樣式和型別檢查可以按以下方式執行：

uv run ruff check
uv run ruff format
uv run mypy

單元測試¶

Sphinx is tested using pytest for Python code and Jasmine 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:

列出所有可能的目標：
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.14:
```
tox -e py314
```
Arguments to pytest can be passed via tox, e.g., in order to run a particular test:
```
tox -e py314 tests/test_module.py::test_new_feature
```

你也可以在本機環境中安裝依賴來進行測試：

uv run pytest

或者使用 pip：

python -m pip install . --group test
pytest

若要執行 JavaScript 測試，請使用 npm：

npm install
npm run test

小訣竅

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

On Unix systems, you can check the presence and location of the firefox binary at the command-line by running command -v firefox.

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.
Tests should be quick and only test the relevant components, as we aim that the test suite should not take more than a minute to run. In general, avoid using the app fixture and app.build() unless a full integration test is required.

在 1.8 版被加入: Sphinx 還會執行 JavaScript 測試。

在 1.5.2 版的變更: Sphinx 已從 nose 切換為 pytest。

貢獻文件¶

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.

Todo

Add a more extensive documentation contribution guide.

建置文件¶

若要建置文件，請執行以下命令：

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

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, use sphinx-autobuild to run the following command:

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

翻譯¶

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.

These Sphinx core messages are translated using the online Transifex platform.

平臺上的翻譯字串將由維護者在新的發行版之前拉取至 Sphinx 儲存庫。

我們不接受直接修改翻譯檔案的拉取請求。相反地，請透過 Transifex 平臺貢獻翻譯。

給維護者的翻譯備註¶

The transifex CLI (tx) 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 utils/babel_runner.py update afterwards to make sure the .po file has the canonical Babel formatting.

Sphinx uses Babel to extract messages and maintain the catalog files. The utils directory contains a helper script, 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 以送交來源檔及編譯後的型錄。

When a new locale is added, 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.

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 --fresh-env option.
Use the sphinx-build --pdb option to run pdb on exceptions.
使用 node.pformat() 與 node.asdom().toxml() 來生成文件結構的可列印表示方式。
將組態變數 keep_warnings 設為 True，這樣警告訊息便會顯示於生成的輸出中。
將組態變數 nitpicky 設為 True，這樣 Sphinx 就會對沒有已知目標的參考提出警告。
在 Docutils 組態檔中設定除錯選項。

更新生成的檔案¶

JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js and stopword files in sphinx/search/_stopwords/ are generated from the Snowball project by running utils/generate_snowball.py.

Minified files in sphinx/search/minified-js/*.js are generated from non-minified ones using uglifyjs (installed via npm). See sphinx/search/minified-js/README.rst.
The searchindex.js files found in the tests/js/fixtures/* directories are generated by using the standard Sphinx HTML builder on the corresponding input projects found in tests/js/roots/*. The fixtures provide test data used by the Sphinx JavaScript unit tests, and can be regenerated by running the utils/generate_js_fixtures.py script.