貢獻

我們感謝您協助改進此文件和我們的函式庫！

如果此文件不清楚或缺少步驟，請開啟一個 issue。

開發流程

如果您有興趣貢獻程式碼或文件，我們強烈建議您在開發環境中安裝 Sphinx-Gallery 的開發版本。如果您不熟悉 git/github 工作流程，請參閱 Github 的專案貢獻指南。

本指南假設您熟悉 Github 工作流程，並側重於貢獻 Sphinx-Gallery 的特定方面。

取得最新原始碼

您可以從我們的 Github 儲存庫取得最新的開發原始碼。

git clone https://github.com/<your github user name>/sphinx-gallery

建立專用環境

我們強烈建議您建立一個虛擬環境來開發 Sphinx Gallery，以將其與系統上的其他 Python 安裝隔離。

建立新的虛擬環境

python -m venv <file folder location>

使用以下其中一種方法啟動虛擬環境

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1

安裝相依性

大多數的 Sphinx Gallery 相依性都列在 pyproject.toml 中，可以從這些檔案中安裝

python -m pip install --editable ".[dev]"

Sphinx Gallery 要求安裝 setuptools。它通常與 Python 一起打包，但如有必要，可以使用 pip 安裝

python -m pip install setuptools

安裝以進行開發

可編輯安裝表示環境 Python 將始終使用您程式碼的最新變更版本。若要以可編輯模式安裝 Sphinx Gallery，請確保您位於 sphinx-gallery 目錄中

cd sphinx-gallery

然後使用可編輯標誌安裝

python -m pip install -e .

驗證安裝

執行測試，檢查您是否已準備就緒

python -m pytest sphinx_gallery

並建置文件

cd doc
make html

安裝 pre-commit 鉤子

pre-commit 鉤子會檢查貢獻程式碼和文件中的拼寫和格式等事項。若要設定 pre-commit 鉤子

python -m pip install pre-commit
pre-commit install

準則

測試

所有程式碼貢獻都應經過測試。我們使用 pytest 測試框架和 tinybuild 來建置測試頁面。測試可以在 sphinx_gallery/tests 中找到。

tinybuild

tinybuild 設計為最小的完整 sphinx 文件建置，您可以使用 make html 從 tinybuild/doc 執行，以獲得傳統的建置體驗。

tinybuild 在 tests/test_full.py 中執行，以使用 tests/doc/tinybuild 中的 .rst 文件建置測試頁面。測試會檢查 html 輸出，以驗證 .rst 檔案中指令的行為。