NumPy 專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

開放原始碼機構：
NumPy
技術文件撰寫者：
cooperrc
專案名稱：
社群教育的 NumPy 說明文件
專案長度：
標準長度 (3 個月)

Project description

簡介

NumPy 在免費的開放原始碼軟體程式庫中提供乾淨且快速的陣列式運算服務。這是 SciPy 堆疊中用於科學運算的基本套件 [1]。目前有超過 3.7 萬個專案用於高效率的陣列運算 [2]。新網站會透過應用程式和個案研究 [1] 詢問 NumPy 使用者。新使用者找到說明文件頁面時，會看到多個「Start Here」連結和簡介教學課程，對初學者來說可能不知道，例如使用 NumPy 基本概念/位元組間切換。我在十年前就開始使用 NumPy。我發現自己會拼湊出網誌文章、課程筆記和 StackExchange 回答，避免再次填寫 NumPy 說明文件。目前有超過 36 萬個 StackExchange 對話負責處理 NumPy。我想像一下其他使用者在 NumPy 的成功路徑差不多，教育工具的構成元素是溝通與社群 [4]。說明文件需要建立一個能反映專案目標目標的社群。為新使用者提供的說明文件內容必須一致、清楚。教學課程應為新使用者提供易於操作的步驟，並讓他們放心使用程式庫 [3]。本文件應歡迎新使用者加入 NumPy 社群。文件的架構、步調及作者都需要打造一個歡迎探索與溝通的空間。本提案將整理並填補目前的 NumPy 說明文件中的缺口，讓新使用者獲得教育資訊並歡迎新加入社群。

透過測試和實驗 [4,5] 獲得使用者溝通所需的知識。知識取決於測試和評估的方法。在教學內容中提供明確目標和應用程式，可讓使用者測試及評估新的想法和方法。社群可以建立知識庫，增進技能、知識和應用程式。教學空間有雙重便利性，首先，新手和資深使用者都有一套明確的目標，可用來測試和打造實驗。其次，潛在技術文件貢獻者也會有充分的空間，說明他們的目標、方法和解決方案。使用教學空間可立即派上用場，讓新使用者和可能的貢獻者更容易取得 NumPy 的說明文件。目前知識

John Dewey 認為學習的基礎是真正的體驗 [4]。NumPy 社群提供大量實際體驗，也可以與其他使用者分享。教育是必須以社群與通訊為基礎。說明文件頁面經過編排，讓新使用者清楚體驗 NumPy。同時也會建立結構化範本，方便潛在貢獻者在 NumPy 傳達經驗。

軟體說明文件 [3] 有四個大範圍的群組空間：教學課程空間、說明空間、說明空間和參考空間。NumPy 說明文件在教學課程空間中有許多文件，涵蓋了說明內容及如何分配教學內容。教學課程空間應著重於使用者教育，並提供可輕鬆重複的步驟來傳達想法。教學示範空間提供更多目標導向的程序，讓使用者可在實際應用程式中套用。說明空間提供每個函式中詳細的文件字串。目前的教學課程和教學聊天室沒有清楚標示，有時也會進入說明和參考空間。您可以參考「絕對新手」的教學課程影片，參考 Matlab 使用者參考的豐富指引，利用「NumPy 給 Matlab 使用者」來建立 NumPy 程式碼。清楚區分這四個空格，可讓說明文件更清楚明瞭。

知識庫/未滿足的需求

目前的說明文件涵蓋許多必要主題，但教學課程、操作說明、說明和參考聊天室的區別並不清楚。導致潛在貢獻者感到困惑。新使用者可能會因教學課程章節的解說和參考資源而感到不堪負荷，潛在貢獻者也會難以做出貢獻。我為新手和可能的文件貢獻者提出更易於使用的版面配置，在說明文件中提供邏輯流程，並管理新協作者針對使用者提供的教學文件的提取要求。我的長期目標是打造說明文件社群，藉此從說明文件中學習，就能獲得有益的教育體驗。這個說明文件模型可以為新手和潛在貢獻者提供實際經驗。

原因

這份 Google 文件夏日提案十分重要，能幫助我達成教學和職涯目標。我在所有課程中都會使用 NumPy 和 SciPy。目前的文件不容易瀏覽，我想運用自己教導非 CS 主題編寫程式碼來整理、編輯和彌補目前教學課程中的缺口的經驗。接著，我可以將說明文件當做教科書和參考資源，用於自己的課程。我使用 Python 和 製作了數十個教學課程、練習和範例。我想將其中部分內容轉換成教學課程和操作說明。我已經讓超過 800 位學生使用 NumPy (也就是 Scipy 堆疊的一部分)，另外有許多學生想成為秋季文件的貢獻者。我在康乃狄克州機械工程大學學了 4 年，教授了超過 30 小時的課程。

特定目標

我針對這個 Google 文件夏日提案有三項特定目標：1. 整理目前的說明文件，2. 編輯目前的教學課程 (新手指南、陣列建立、索引、線性代數和適用於 Matlab 的 NumPy)，將參考資訊移至說明空間，以及 3。與學生一起製作教學教材。每個特定目標對提案都有預期結果。

這三項特定目標是讓說明文件更貼近新使用者的需求，並為可能的貢獻者提供結構。這個目標也能幫助我們進一步實現長期目標，持續推動 NumPy 說明文件社群成長。 預期成果

我的預期結果有三個，例如：1. 修改說明文件網頁，其中清楚分隔四個空格：教學課程、操作說明、說明和參考資料，2. 新教學課程的內容包括：讀取和寫入陣列、建立陣列 (np.zeros、np.ones、np.block 等)，以及 NumPy 中的元素與線性代數運算，以及 3. 精選教學空間。

這些預期結果將有助於新使用者透過文件逐步瀏覽文件、為可能的講者提供清楚的樣式和格式、讓現行教學課程的內容更加精簡且易於遵循，並將說明內容移到獨立章節；新的說明文件貢獻者也能在不用建立完整的 Sphinx 文件的情況下，為操作說明章節提供少量用途。我們希望持續打造教學與學習社群。

新的說明文件貢獻者可為數百萬名使用者提供小型使用情境，不必建構完整的 Sphinx 說明文件。我們希望持續打造教學與學習社群。這份提案文件會模仿目前的開放原始碼文件 (例如 Matgraphiclib、Diio 等)。新使用者和潛在貢獻者能更輕鬆學會在自身領域和軟體中應用 NumPy。

專案時程為 9 月 14 日至 11 月 30 日。第一步是建立說明文件，並將目前教學課程中的內容分隔成教學課程、教學和說明內容。這項作業將在專案前五週分別完成，結果 1 及 2 修訂網站和教學課程的一部分。提議的文件整理於下方「提議的文件」中。

建議的說明文件：

i.Tutorials:

  • 初學者的絕對基本知識 (移除安裝作業，pandas 匯入/匯出作業可替換為 numpy.loadtxt?)
  • 「什麼是 numpy」的連結
  • 這裡的連結可前往基本安裝操作說明
  • 快速入門教學課程 (搭配 Python 教學課程的後續使用)
  • 使用 NumPy 陣列
  • 陣列建立 (np.zeros、np.ones、np.block 等)(寫入：中低優先順序)
  • 元素級運算 (+、-、* /) 和線性代數運算 (+、-、@、linalg.solve) (write:medPriority)
  • 使用 Numpy 讀取及寫入資料 (寫入：高優先順序)
  • 建立索引

ii. 操作說明：

  • n 維陣列上的線性代數 (可用於編輯標題及說明，也可以將標題變更為「使用 Numpy 線性代數進行圖片處理」)
  • numpy-tutorials 教學內容 (進行中) 連結

iii. 說明：

  • 資料類型
  • I/O 和 Numpy
  • 建立索引
  • 廣播
  • 位元組交響
  • 結構化陣列
  • 編寫自訂陣列容器
  • 將 ndarray 加入子類別
  • 其他

iv. 參考空間：

  • 詞彙
  • Numpy API 參考資料
  • Matlab 使用者適用的數值 (等量資料表是很好的參考表，但陣列/矩陣討論會分散注意力且似乎已淘汰)

完成本 Google 搜尋季文件後，我提出以下成果：

  • 修改過的說明文件網頁，明確區隔出四個空間：教學課程、操作說明、說明和參考資料
  • 新的教學課程：建立陣列 (np.zeros、np.ones、np.block 等)、元素相關運算 (+、-、* /) 和線性代數運算 (+、-、@、linalg.solve)，以及使用 Numpy (高優先順序) 讀取及寫入資料
  • 提供教學文件來增進使用者貢獻，並協助社群在教學與學習方面實現目標

各項結果都會按照下表所列的步驟 1 到 3 列出。在將「提議的文件」送交審查時，高優先順序的「讀取/寫入陣列」教學課程將做為結果 2 的提取要求寫入。在檢閱修訂過的網站並更新「讀取/寫入陣列」教學課程期間，我會開始撰寫教學課程，瞭解如何使用 NumPy 函式 (例如 np.ones、np.zeros、np.diag) 建立陣列。剩餘的時間將用於回應提取要求問題，並開始寫入排名 3 教學課程：Python 中的元素與線性代數作業。

第三個成果就是建議康乃狄克大學的學生在 numpy-tutorials 存放區中建立文件。提交的教學課程或操作說明文件會是 Jupyter 筆記本，其中使用 NumPy 來解決工程問題。我會利用部分課程筆記/範例來提交範例筆記本。我會建議學生在建立範本和取景配置時，採用版面配置和架構。這個成果可以帶給學生真誠的體驗，讓更多人瞭解概念和解決方案。這是讓學生參與 NumPy 社群及學習的絕佳機會。

結果 1：修改網站 Deliverable Date Fork Repository and Build Docs with Sphinx 9/21 在 10 月 21 日透過 10 月 1 日定義和連結四個聊天室 建立網頁 將目前的教學課程移至適當聊天室，以及建立文件 10/10 將 PR3 提交至 11/10 修訂成果/建議 在網站修改 11 項結果，同時修改 PR3 結果

結果 2：修訂教學課程 交付日期 查看教學課程修訂版本排名 9/21 將目前的教學課程內容排序成教學課程和說明空間 10/1 寫入排名 1：讀取/寫入陣列 10/10 將 PR 提交至 GitHub 進行分隔並修訂 10/20 撰寫 10/20 PRa PRa PRa PRa PRa 和 PRa PR

教學課程修訂建議排名 (視導師/社群而定)：

  1. 讀取/寫入陣列目前空白頁面

  2. 建立陣列 (np.zeros、np.ones、np.block 等)不存在：可協助新使用者瞭解常見的陣列建立/互動工具，並加以示範

  3. 元素相關和線性代數運算 (+、-、* 和 +、-@,linalg.solve) 不存在：這對於 1 項目特別有用。Matlab 使用者和 2. 採用線性代數 (機器學習、線性迴歸等) 的使用者

結果 3：精選解說空間 交付日期 外部連結(問題/範例) 建構教學範例 (候選：如何找出吉他字串的自然頻率 10/20
為已完成的教學課程範本 PR 和 Framtuing 可能的貢獻內容，招募其他貢獻者)：

預期重要性

這個 Google Summer of Docs 提案製作 NumPy 文件 、填寫網站上缺少的教學課程，並可獲得文件貢獻者。我任職於機械工程教授，打算區隔說明文件，讓學生能夠瀏覽文件並輕鬆找到入門教學課程和實作指南。提供經過分類的說明文件：教學課程、操作說明、參考資料和說明，可為潛在協作者提供結構化範例，協助他們建立新資源。你提出的說明文件是針對新手和有經驗的使用者提供教育與溝通的經驗。康乃狄克州大學學生建議採用的文件建議文件，將會將這些想法轉化為實際做法。我們希望所有使用者都能找到充滿實驗、學習和加入 NumPy 社群的場所。

參考資料

  1. NumPy.org 網站存取時間：2020 年 7 月。
  2. NumPy GitHub 存放區
  3. 說明文件系統。Divio.com 於 2020 年 7 月存取。
  4. Dewey、John。民主與教育：Gutenberg 計畫，2015 年 8 月。
  5. Dewey、John。任職於 Certainty George Allen And Unwin Limited 的任務，2005 年 6 月。