貢獻 Sphinx¶

您有很多種方式可以貢獻 Sphinx，無論是提交錯誤回報或功能請求、撰寫新的文件，或是提交針對新增或修正行為的修補程式。本指南旨在說明如何開始著手進行。

取得協助¶

Sphinx 社群維護了許多郵寄清單和 IRC 頻道。

Stack Overflow，標籤為 python-sphinx: 關於使用和開發的問答。
GitHub Discussions 問答: 用於討論的問答形式論壇。
sphinx-users <sphinx-users@googlegroups.com>: 使用者支援郵寄清單。
sphinx-dev <sphinx-dev@googlegroups.com>: 關於開發相關討論的郵寄清單。
irc.libera.chat 上的 #sphinx-doc: 用於開發問題和使用者支援的 IRC 頻道。

錯誤回報與功能請求¶

如果您在使用 Sphinx 時遇到問題，或是有新功能的想法，請提交至 GitHub 上的 issue tracker。

對於錯誤回報，請包含建置過程中產生的輸出，以及 Sphinx 在遇到未處理的例外狀況後建立的日誌檔。此檔案的位置應顯示在錯誤訊息的末尾。另請包含 sphinx-build --bug-report 的輸出。

包含或提供相關原始碼檔案的連結可能有助於我們修正問題。如果可以，請嘗試建立一個會產生錯誤的最小專案並張貼出來。

貢獻程式碼¶

Sphinx 原始碼使用 Git 管理，並託管於 GitHub。新貢獻者向 Sphinx 提交程式碼的建議方式是 fork 此儲存庫，並在將變更提交到您的 fork 後提交 pull request。pull request 接著需要由核心開發人員之一批准，然後才能合併到主要儲存庫中。

開始使用¶

在開始修補程式之前，我們建議先檢查是否有未解決的問題，或是開啟一個新的 issue，以開始討論關於功能想法或錯誤。如果您對問題或您的變更感到不自在或不確定，請隨時發起討論。

以下是開始在 Sphinx 上開發所需的基本步驟。

在 GitHub 上建立帳戶。
Fork 主要的 Sphinx 儲存庫 (sphinx-doc/sphinx)，使用 GitHub 介面。

將 fork 的儲存庫複製到您的電腦。

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

設定虛擬環境。

這對於單元測試不是必要的，這要歸功於 tox，但如果您希望在本機執行 sphinx-build 或在沒有 tox 協助下執行單元測試，則這是必要的
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
建立新的工作分支。選擇您喜歡的任何名稱。
```
git switch -c feature-xyz
```
盡情 Hack。

編寫您的程式碼，並附帶測試，以顯示錯誤已修正或功能如預期般運作。
如果修復或功能並非微不足道（小型文件更新、錯字修正），則在 CHANGES.rst 中新增一個項目符號，然後提交
```
git commit -m 'Add useful new feature that does this.'
```
將分支中的變更推送到您在 GitHub 上的 fork 儲存庫
```
git push origin feature-xyz
```
從您的分支提交 pull request 到 master 分支。

GitHub 識別某些短語，這些短語可用於自動更新 issue tracker。例如，在您的 pull request 的內文中包含 “Closes #42” 將在 PR 合併後關閉 issue #42。
等待核心開發人員或貢獻者審查您的變更。

程式碼風格¶

在為 Sphinx 撰寫程式碼時，請遵循這些指南

嘗試使用與專案其餘部分相同的程式碼風格。
對於非微不足道的變更，請更新 CHANGES.rst 檔案。如果您的變更會改變現有行為，請記錄下來。
新功能應記錄在文件中。在適當的地方包含範例和使用案例。如果可能，請包含一個顯示在產生的輸出中的範例。
在新增組態變數時，請務必記錄下來，並且在它夠重要的情況下更新 sphinx/cmd/quickstart.py。
新增適當的單元測試。

樣式和類型檢查可以如下執行

ruff check .
mypy

單元測試¶

Sphinx 使用 pytest 測試 Python 程式碼，並使用 Jasmine 測試 JavaScript。

若要執行 Python 單元測試，我們建議使用 tox，它提供了許多目標，並允許針對多個不同的 Python 環境進行測試

列出所有可能的目標
```
tox -av
```
針對特定 Python 版本（例如 Python 3.13）執行單元測試
```
tox -e py313
```
pytest 的引數可以透過 tox 傳遞，例如，為了執行特定的測試
```
tox -e py313 tests/test_module.py::test_new_feature
```

您也可以透過在本機環境中安裝相依性來進行測試

pip install .[test]

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

npm install
npm run test

提示

jasmine 需要 Firefox 二進位檔才能作為測試瀏覽器使用。

在 Unix 系統上，您可以透過執行 command -v firefox 在命令列檢查 firefox 二進位檔是否存在及其位置。

新的單元測試應包含在必要的 tests/ 目錄中

對於錯誤修正，請先新增一個在沒有您的變更時會失敗，而在套用變更後會通過的測試。
需要執行 sphinx-build 的測試應盡可能整合到現有的測試模組之一中。
測試應該快速且僅測試相關組件，因為我們的目標是測試套件的執行時間不應超過一分鐘。一般來說，除非需要完整的整合測試，否則應避免使用 app fixture 和 app.build()。

版本 1.8 新增: Sphinx 也執行 JavaScript 測試。

版本 1.5.2 變更: Sphinx 從 nose 切換到 pytest。

貢獻文件¶

貢獻文件涉及修改 doc/ 資料夾中的原始碼檔案。若要開始使用，您應先遵循開始使用，然後按照以下步驟操作文件。

以下章節說明如何開始貢獻文件，以及我們使用的一些不同工具的關鍵面向。

建置文件¶

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

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

這將會解析 Sphinx 文件的原始碼檔案，並產生 HTML 讓您可以在 build/sphinx/html 中預覽。

您也可以建置文件的即時版本，讓您可以在瀏覽器中預覽。它會偵測變更，並在您進行編輯時重新載入頁面。若要執行此操作，請使用 sphinx-autobuild 執行以下命令

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 上翻譯。由 transifex_client Python 套件提供的 tx 用戶端工具可用於從 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 設定檔中設定除錯選項。

更新產生檔案¶

sphinx/search/non-minified-js/*.js 中的 JavaScript 詞幹演算法是使用 snowball 產生的，方法是複製儲存庫，執行 make dist_libstemmer_js，然後解壓縮在 dist 目錄中產生的 tarball。

sphinx/search/minified-js/*.js 中的縮小檔是使用 uglifyjs (透過 npm 安裝) 從非縮小檔產生的，並使用 -m 選項啟用名稱混淆。
在 tests/js/fixtures/* 目錄中找到的 searchindex.js 檔案是透過在 tests/js/roots/* 中找到的對應輸入專案上使用標準 Sphinx HTML 建置器產生的。這些 fixtures 提供 Sphinx JavaScript 單元測試使用的測試資料，並且可以透過執行 utils/generate_js_fixtures.py 腳本重新產生。