Ctrl+K

貢獻 SciPy 文件#

我們很樂意聽取並修正文件中的錯誤。但是為了處理最大的問題，我們最終不得不延遲或忽略一些錯誤報告。以下是最好著手處理的錯誤類型。

首要優先處理的是 **技術上的不準確** – 例如文件字串 (docstring) 缺少參數、函數/參數/方法的描述有誤等等。其他「結構性」錯誤，如連結失效，也具有優先權。所有這些修正都很容易確認和實施。如果您知道如何操作，可以提交 pull request (PR) 來修正；否則請開啟 issue。

**錯字和拼字錯誤** 的優先級較低；我們歡迎您回報這些錯誤，但可能無法立即修正。這些錯誤也可以透過 pull request 或 issue 來處理。

明顯的 **措辭** 錯誤（例如遺漏了 “not”）屬於錯字類別，但其他的措辭修改 – 即使是針對文法 – 也需要判斷，這提高了門檻。可以想像有些情況下，不清楚是否應該進行「修正」，例如：

  • 試圖「修正」所有牛津逗號的使用（或未使用）。

  • 常見用法的正確性正在演變的情況，例如 “comprised of”。

最容易接受的修正是那些原始版本明顯且明確錯誤的；需要細微編輯判斷的更改最好避免。（但請注意，這不是關於更新文件以修正令人困惑的陳述，或以其他方式處理使用者回報的文件問題。）

注意

作為一般指引，請嘗試累積小的文件變更（例如錯字），而不是逐一發送。在可能的情況下，也請務必使用正確的命令來跳過 CI 檢查文件變更。

在 C 或 Fortran 擴充模組中定義的某些函數/物件，其文件字串 (docstring) 與實際程式碼分開定義。請務必使用 grep 或其他類似工具搜尋您要尋找的函數文件字串。

使用 Sphinx 在本地端渲染文件#

SciPy 文件字串 (docstring) 使用 Sphinx 和 PyData Sphinx theme 渲染為 HTML。文件字串的寫作方式在 文件風格 中說明；本文檔說明如何檢查文件字串是否正確渲染。

如需影片教學，請參閱 使用 Sphinx 渲染 SciPy 文件 。

若要在您自己的機器上渲染文件

  1. 確保您有一個可運作的 SciPy 建置版本（請參閱 從原始碼編譯）。

  2. 然後執行 python dev.py doc 以建置文件。第一次可能需要一些時間，但後續的文件建置通常會快得多。

  3. 在 doc/build/html/ 中檢視文件。您可以從 index.html 開始瀏覽，或者直接跳到您感興趣的檔案。

互動式範例

文件字串 (docstring) 中的範例可以使用 jupyterlite-sphinx 變成互動式。在乾淨的文件建置中，預設會隱藏將範例區段轉換為嵌入式互動式筆記本的按鈕。若要在本地端建置文件後啟用互動式範例，請編輯 scipy/doc/build/html/ 中執行時期設定檔 try_examples.json 中的 ignore_patterns 列表。乾淨文件建置中此檔案的初始版本為：

{
    "global_min_height": "400px",
    "ignore_patterns": [".*"]
}

將文件字串 (docstring) 範例轉換為嵌入式筆記本的按鈕，將針對所有符合 ignore_patterns 列表中 JavaScript Regex 模式的 URL 路徑隱藏。[".*"] 包含一個符合所有 URL 路徑的模式。從列表中移除此模式將為所有範例啟用互動性。請參閱 jupyterlite-sphinx TryExamples 指令 的文件以取得更多資訊。

注意

  • 當 Sphinx 文件重新建置時，對某些文件的變更可能不會生效。在這種情況下，您可以刪除 scipy/doc/build 和 source/reference/generated 目錄，然後再次建置，從頭開始建置。

  • 如果上述命令找到的 SciPy 版本與 repo 中最新 commit 的版本不同，您會看到類似以下訊息：

    installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'

    這表示您可能正在使用錯誤的 SciPy 安裝版本，請使用 python -c "import scipy; print(scipy.__file__)" 檢查。

  • 互動式範例在 CI 建置中不可用。若要在 JupyterLab 環境中於本地端查看互動式範例，您可以使用：

    python -m http.server --directory doc/build/html

    文件頁面應可在 https://127.0.0.1:8000/ 上存取。

在雲端檢查文件#

一旦 PR 開啟，您就可以檢查文件是否在雲端正確渲染。

  1. 登入 GitHub。

  2. 使用您的 GitHub 帳戶登入 CircleCI。

  3. 返回 GitHub，在 PR 底部，選擇「顯示所有檢查」。

  4. 在「在這裡檢查渲染的文件！」旁邊，選擇「詳細資訊」。

以 Jupyter 筆記本新增或編輯教學文件#

在 SciPy 樹狀結構的 doc/source/ 資料夾下，您可以找到一些以 MyST-NB 格式撰寫的文件。這些檔案是可執行的，這表示它們的內容在建置 SciPy 文件時（在本地端或 CI 中）會被執行，並且執行產生的任何輸出都會渲染到最終的 HTML 檔案中。

如果您有以 Jupyter 筆記本格式撰寫的文件（.ipynb 檔案），並且想要將其作為 SciPy 文件的一部分提交，則有兩個選項：您可以將其轉換為 MyST Markdown 檔案，僅使用 .md 檔案，或者您可以將您的 .ipynb 檔案與 .md 檔案配對，並同時使用兩者。請注意，不應將 .ipynb 檔案提交到 SciPy 文件中。

如需更多詳細資訊，請查閱 MyST-NB 文件。您也可以查閱 NumPy 教學文件上的配對教學，以取得更多關於 MyST-NB、Jupytext 和配對筆記本的資訊。

如何將 .ipynb 檔案轉換為可執行的 .md 檔案#

如果您不需要保留 .ipynb 檔案，並且只想使用 MyST Markdown，請按照以下步驟操作。

  1. 安裝 jupytext 工具，使用 pip install jupytext 或 conda install jupytext -c conda-forge

  2. 清除您 .ipynb 檔案中的所有輸出。

  3. 在您的終端機中，執行 jupytext notebook.ipynb --to myst，其中 notebook.ipynb 應替換為您要轉換的檔案。

現在，產生的 .md 檔案（MyST Markdown 格式）應包含類似於以下的 preamble，表示這是一個可執行檔案：

---
jupytext:
   text_representation:
      extension: .md
      format_name: myst
      format_version: 0.13
      jupytext_version: 1.14.0
kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
---

您不需要編輯此 preamble，因為它是自動產生的。

在 Jupyter Notebook 應用程式中開啟 MyST Markdown 檔案#

如果您已安裝 jupytext 工具，您可以在 Jupyter Notebook 應用程式中開啟 MyST Markdown .md 檔案並執行它們，就像您對 .ipynb 檔案所做的一樣。

文件指南#

使用 “must”，而非 “should”#

當指定輸入參數的必要條件時，使用 “must” 比 “should” 更佳。對於許多英語使用者來說，“must” 比 “should” 隱含更強烈的約束，例如 “I must have oxygen to live” 相對於 “I should exercise more”。

是

Parameters
----------
x : float
    `x` must be nonnegative.

否

Parameters
----------
x : float
    `x` should be nonnegative.

‘versionadded’ 標記的使用#

  • 對於新函數，‘versionadded’ 標記應放在「Notes」區段中，而不是 文件字串 (docstring) 開頭的描述中。

  • 對於新增到現有函數的新參數，‘versionadded’ 標記應放在「Parameters」區段中參數描述的末尾。

在「References」區段中引用維基百科文章#

可以接受使用維基百科文章作為參考文獻。在建立參考文獻的引用時，請包含文章標題、「Wikipedia」名稱（類似於期刊標題的給法）和 URL。

是

.. [1] "Zeta Distribution", Wikipedia,
       https://en.wikipedia.org/wiki/Zeta_distribution

否

.. [1] https://en.wikipedia.org/wiki/Zeta_distribution

參考文獻中的 DOI#

強烈建議在參考文獻中使用 DOI。DOI 有特殊的 Sphinx 語法：:doi:。例如：

.. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
       C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
       203-215, :doi:`10.1016/j.patcog.2018.09.014`

（arXiv 文章也有特殊的標記可用：:arxiv:。）

項目符號列表#

這與其說是指南，不如說是提醒關於項目符號列表的 Sphinx 標記。不正確的縮排使用非常常見，因此值得在此提及。

建立項目符號列表時

  • 不要以前一行結尾 ::。

  • 不要縮排項目符號。

  • 在列表前後包含一個空白行。

一些範例

是

Some text that precedes this interesting list:

* The first item in the list.
* The second item in the list.
* You get the idea.

Some text that follows the list.

否

Some text that precedes this interesting list:

  * The first item in the list.
  * The second item in the list.
  * You get the idea.

Some text that follows the list.

否

Some text that precedes this interesting list:
* The first item in the list.
* The second item in the list.
* You get the idea.
Some text that follows the list.

自包含範例#

每個「範例」區段（無論是在文件字串 (docstring) 還是通用文件中）都必須是自包含的。這表示所有匯入都必須是顯式的，使用的資料必須已定義，並且程式碼在複製貼上到新的 Python 直譯器中時應該「可以直接運作」。

是

>>> import numpy as np
>>> rng = np.random.default_rng()

否

>>> rng = np.random.default_rng()

可能（且建議）的是將程式碼區塊與說明文字交錯排列。空白行必須將每個程式碼區塊與說明文字分隔開來。

是

Some initial text

>>> import numpy as np
>>> rng = np.random.default_rng()

This is some explanation

>>> rng.random(10)

範例和隨機性#

在持續整合 (CI) 套件中，範例會被執行，並且輸出會與提供的參考進行比較。主要目標是確保範例是正確的；失敗會警告我們範例可能需要調整（例如，因為 API 在撰寫後已變更）。Doctest 並不旨在用作底層實作的單元測試。

如果需要隨機數產生器，則必須使用 np.random.Generator。建立 NumPy Generator 的標準方法是使用 np.random.default_rng。

是

>>> import numpy as np
>>> rng = np.random.default_rng()
>>> sample = rng.random(10)

是

>>> import numpy as np
>>> rng = np.random.default_rng(102524723947864966825913730119128190984)
>>> sample = rng.random(10)

否

>>> import numpy as np
>>> sample = np.random.random(10)

設定產生器物件的種子是可選的。如果使用種子，請避免使用常見的數字，而是使用 np.random.SeedSequence().entropy 產生種子。如果未提供種子，則在執行 doctest 時會使用預設值 1638083107694713882823079058616272161。在任何一種情況下，渲染的文件都不會顯示種子。目的是勸阻使用者在其程式碼中複製/貼上種子，而是對程式中種子的使用做出明確的決定。結果是使用者無法完全重現範例的結果，因此使用隨機資料的範例不應參考基於隨機資料的精確數值，也不應依賴它們來闡述其觀點。

Legacy 指令#

如果函數、模組或 API 處於 legacy 模式，表示為了向後相容性而保留，但不建議在新程式碼中使用，則可以使用 .. legacy:: 指令。

預設情況下，如果未使用任何引數，legacy 指令將產生以下輸出：

Legacy

此子模組被視為 legacy，將不再接收更新。雖然我們目前沒有移除它的計畫，但我們建議新程式碼改用更現代的替代方案。

我們強烈建議您也新增自訂訊息，例如取代舊 API 的新 API。此訊息將附加到預設訊息中。

.. legacy::

   New code should use :mod:`scipy.fft`.

將產生以下輸出：

Legacy

此子模組被視為 legacy，將不再接收更新。雖然我們目前沒有移除它的計畫，但我們建議新程式碼改用更現代的替代方案。新程式碼應使用 scipy.fft。

最後，如果您想提及函數、方法（或任何自訂物件）而不是子模組，您可以使用可選引數：

.. legacy:: function

這將產生以下輸出：

Legacy

此函數被視為 legacy，將不再接收更新。雖然我們目前沒有移除它的計畫，但我們建議新程式碼改用更現代的替代方案。

—

本頁內容