NEP 44 — NumPy 文件重組#

作者:

Ralf Gommers

作者:

Melissa Mendonça

作者:

Mars Lee

狀態:

已接受

類型:

流程

建立於:

2020-02-11

決議:

https://mail.python.org/pipermail/numpy-discussion/2020-March/080467.html

摘要#

本文檔提議重組 NumPy 文件，包括形式和內容，目標是使其對初學者和經驗豐富的使用者更具組織性和可發現性。

動機和範圍#

請參閱此處以查看最新文件的首頁。組織結構相當混亂且不合邏輯（例如，使用者和開發人員文件混合在一起）。我們提出以下建議

  • 將文件重新組織為[1]中提到的四個類別，即教學、操作指南、參考指南和說明（更多內容如下）。

  • 為教學和操作指南建立專用章節，包括關於如何建立新內容的指導；

  • 為需要更深入描述的關鍵概念和技術新增說明章節，其中一些將從參考指南中重新排列。

使用方式和影響#

文件是任何軟體專案的基本組成部分，尤其是開源專案。在 NumPy 的案例中，許多初學者可能會因目前的文件結構而感到沮喪，因為很難發現要學習的內容（除非使用者清楚地知道要在參考文件中尋找什麼，但情況並非總是如此）。

查看任何搜尋引擎上「NumPy 教學」搜尋的結果，也可以瞭解對此類內容的需求。擁有使用最新內容和技術編寫的官方高階文件，肯定意味著更多使用者（和開發人員/貢獻者）參與 NumPy 社群。

向後相容性#

重組將有效地要求完全重寫連結和目前的部分內容。來自社群的意見將有助於識別不應中斷的關鍵連結和頁面。

詳細描述#

如[1]文章中所討論的，文件內容有四個類別

  • 教學

  • 操作指南

  • 說明

  • 參考指南

我們建議使用這些類別作為我們在新增新的文件章節時使用的類別（用於編寫和審閱）。

這樣做的理由是，對於開發人員/文件編寫人員和使用者而言，都很清楚每條資訊應放在哪裡，以及每份文件的範圍和語氣。例如，如果將說明與基本教學混在一起，初學者可能會感到不知所措和疏遠。另一方面，如果參考指南包含基本操作指南，經驗豐富的使用者可能難以快速找到他們需要的資訊。

目前，網路上有很多關於 NumPy 或使用 NumPy 的部落格和教學。這樣做的一個問題是，如果使用者搜尋這些資訊，他們可能會在找到當前官方文件之前，最終找到過時的（非官方）教學。這可能會特別令人困惑，尤其是對於初學者而言。擁有更好的文件基礎架構也旨在解決這個問題，方法是向使用者提供高階、最新的官方文件，並且可以輕鬆更新。

每種文件內容類型的狀態和想法#

參考指南#

NumPy 有相當完整的參考指南。所有函數都有文件記錄，大多數都有範例，而且大多數都與另請參閱章節良好地交叉連結。進一步改進參考指南是許多人可以做（並且正在做）的增量工作。然而，參考指南中有很多說明。這些可以移至文件中更專用的說明章節。

操作指南#

NumPy 沒有很多操作指南。子類別化和陣列鴨子型別章節可能是操作指南的一個範例。可以新增的其他指南包括

  • 平行化（使用 threadpoolctl 控制 BLAS 多執行緒、使用多進程、隨機數字產生等）

  • 儲存和載入資料（.npy/.npz 格式、文字格式、Zarr、HDF5、Bloscpack 等）

  • 效能（記憶體佈局、效能分析、與 Numba、Cython 或 Pythran 一起使用）

  • 編寫適用於 NumPy、Dask、CuPy、pydata/sparse 等的通用程式碼。

說明#

關於基本 NumPy 概念（例如索引、向量化、廣播、(g)ufuncs 和 dtypes）有相當多的內容。可以更好地組織和澄清這些內容，以確保它們真正是關於解釋概念，而不是與教學或操作指南類的內容混合在一起。

除了那些基本的 NumPy 概念之外，幾乎沒有關於其他任何事物的說明。

可以擴展的一些概念範例

  • 副本與檢視；

  • BLAS 和其他線性代數函式庫；

  • 花式索引。

此外，參考指南中有很多說明，應將其移至這個新的專用說明章節。

教學#

編寫更好的教學有很多空間。我們有一個新的NumPy 絕對初學者教學[3]（Anne Bonner 的 GSoD 專案）。此外，我們還需要一些針對具有不同 Python 和 NumPy 經驗水平的教學。這可以使用引人入勝的資料集、想法或故事來完成。例如，使用 numpy.linalg 中的多項式和函數進行曲線擬合可以使用 Keeling 曲線（空氣測量中數十年的 CO2 濃度），而不是使用合成隨機資料。

教學的想法（這些想法捕捉了有意義的事物類型，它們不一定是我們提議實作的確切主題）

  • 僅使用 NumPy 的康威生命遊戲（注意：已在Nicolas Rougier 的書中）

  • 使用遮罩陣列處理時間序列測量中的遺失資料

  • 使用傅立葉轉換分析 Keeling 曲線資料並外推它。

  • 地理空間資料（例如，緯度/經度/時間，以建立每個年份的地圖，透過堆疊陣列，如gridMet 資料）

  • 使用文字資料和 dtypes（例如，使用來自不同人的演講稿，形狀為 (n_speech, n_sentences, n_words)）

來自 Software Carpentry Instructor Training materials 的準備教學文件[2]是對如何編寫有效的課程計畫（教學非常相似）的良好總結。除了新增新的教學之外，我們還提議編寫一份如何編寫教學文件，這將有助於使用者為文件貢獻新的高品質內容。

資料集#

在 NumPy 文件中使用有趣的資料需要讓所有使用者都能存取該資料，無論是在 NumPy 內部還是在單獨的套件中。前者不是最好的主意，因為很難在不顯著增加 NumPy 大小的情況下做到這一點。

在可能的情況下，文件頁面應使用來自scipy.datasets套件的範例。

實作#

目前，NumPy 的文件可能會令人困惑，尤其是對於初學者而言。我們的提案是以以下結構重新組織文件

  • 針對使用者

    • 絕對初學者教學

    • 主要教學章節

    • NumPy 常見任務的操作指南

    • 參考指南 (API 參考)

    • 說明

    • F2Py 指南

    • 詞彙表

  • 針對開發人員/貢獻者

    • 貢獻者指南

    • 底層文件

    • 建置和擴展文件

    • 基準測試

    • NumPy 增強提案

  • Meta 資訊

    • 回報錯誤

    • 發行說明

    • 關於 NumPy

    • 授權條款

後續想法#

除了在一定程度上重寫目前的文件之外，理想情況下，應該有一個技術基礎架構，允許社群做出更多貢獻。例如，如果 Jupyter Notebook 可以按原樣提交作為教學或操作指南，這可能會吸引更多貢獻者並擴大 NumPy 社群。

同樣地，如果人們可以下載某些 Notebook 格式的文件，這肯定意味著人們將減少使用過時的材料來學習 NumPy。

如果新的文件結構使翻譯更容易，也將會很有趣。

討論#

關於此 NEP 的討論可以在 NumPy 郵件列表中找到

參考文獻和註腳#