Matplotlib 專案

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

專案摘要

開放原始碼機構：
Matchartlib
技術文件撰寫者：
brunobeltran
專案名稱：
將「隱含」類型的說明文件標準化，提高功能曝光度
專案長度：
長時間執行 (5 個月)

Project description

動機

過去，matchartlib 的 API 非常仰賴字串做為「隱含類型」的字串。除了模仿 matlab 的 API 以外，這些參數字串可讓使用者將語意豐富的值做為引數傳遞至 mattulib 函式，而無需明確匯入或在前面加上實際 enum 值來傳遞基本繪製選項 (即 plt.plot(x, y, linestyle='solid') 比 plt.plot(x, y, linestyle=mpl.LineStyle.solid) 這類項目更容易輸入且較不冗餘)。

一直以來，這些字串做為列舉的隱含類型大多已發展到更先進的功能。舉例來說，linestyle 現在可以是字串或序列的 2 元組，而且 MarkerStyle 現在可以是字串或 matplotlib.path.Path。雖然許多隱含類型也是如此，但只有 MarkerStyle 是狀態已升級為適當的 Python 類別，且只有 MarkerStyle 是狀態。

由於這些隱含類型本身並不構成類別，因此 Matchartlib 必須自行導入相關解決方案來集中文件並驗證這些隱含類型 (例如 docstring.interpd.update docstring 內插模式和 cbook._check_in_list 驗證工具模式)，而不是使用 Python 類別 (例如文件串) 提供的標準工具鍊和驗證模式 __init__ 等標準工具鍊。

儘管這些解決方案的效用很不錯，但由於沒有明確位置可記錄每種隱含類型，意味著說明文件通常很難找到，但允許值的大型資料表會在整份說明文件中重複出現，而且通常文件中會完全缺少隱含類型範圍的明確陳述式。參考 plt.plot 文件，例如在「Notes」中，「Notes」這個類似 matlab 的格式字串樣式方法說明會提及 linestyle、color 和 markers 選項。傳遞這三個值的方法很多，除了提供提示外，對許多使用者來說，這是唯一瞭解這些選項可能使用值的方式，直到相關教學課程出現為止。我們隨附了 Line2D 屬性表格，目的是向讀者說明可控制繪圖的選項。不過，linestyle 項目確實適合連結至 Line2D.set_linestyle (需要兩次點擊)，並在說明可能的輸入內容的情況下，說明 color 和 markers 項目。color 只是連結至 Line2D.set_color，因此無法針對哪些類型的輸入提供任何直覺。

僅須整理出造成問題的個別文件字串即可修正這個問題，但這個問題可不至於過於系統化。在沒有集中存放說明文件的位置，這只是使得我們為每個隱含類型使用越來越多的詳細說明文件，而重複利用，讓新手使用者更難找到自己需要的參數。然而，目前的系統亦無法永續經營。目前的系統也無法延續上述做法，在說明文件中透過維基百科的走向樣式，逐步拼湊每種隱含類型的心理模型；或從 StackOverflow 範例的重要部分。

結束目標

理想情況下，隱含類型的任何提及都應連結到單一頁面，其中說明該類型可能採用的所有可能值，由最簡單、最常用於最先進或常用於排序。接著，我們不必使用頂層 API 說明文件中寶貴的視覺空間，列舉出特定參數的所有可能的輸入類型，而是利用相同空間提供簡單的敘述，說明參數繪圖的抽象化機制。

如要再次使用 linestyle 的範例，我們希望 LineCollection 文件只需：

  1. 點選連結即可完成可輸入輸入內容的文件 (結合 Line2D.set_linestyle 和線條樣式教學課程的內容組合)。
  2. 參數用途的簡短說明。對 mattulib 進階使用者而言，這是從參數名稱中就能看出的，但對於新使用者，則不需要。

在實際的 LineCollection 文件裡，效果就像在 python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """""" 中一樣，其中 LineStyle 類型參照會由 Sphinx 解析，指向一個具公信力的單一完整說明文件，指出 Mat chartlib 處理線條樣式的方式。

優點

這種方法的一些強大功能包括

  1. 讓每項函式都能以純文字清楚顯示 (不需點選即可)。
  2. 顯示預設選項 (沒有任何點擊)。看到預設選項通常足以應付回訪者的記憶體。
  3. 請針對任一參數的「最常見」和「最簡單」選項提供完整說明，以供瀏覽 (按一下滑鼠) 查看。
  4. 探索更強大的功能和輸入法，例如「向下捲動」，即可查看更多進階選項 (仍只需按一下滑鼠)。
  5. 提供集中式策略，將頂層「API」文件連結至相關的「教學課程」。
  6. 避免使用 API 文件爆炸性，因為掃描每個參數的許多可能選項，會導致個別文件字串變得輕鬆又靈活。

相較於目前的文件，這個方法的其他優點包括：

  1. Google 文件因為集中管理，較不容易過時。
  2. 對許多 mattulib 的「隱含標準」(例如「邊界」與「擴充」) 進行標準化，目前必須透過讀取程式碼才能學習。
  3. 這個程序會突顯 API 一致性相關問題，讓使用者更容易透過 GitHub 問題追蹤工具追蹤，進而改善 API 的程序。
  4. 由於需要剖析的文字量大幅減少，因此文件建構時間縮短。

導入作業

上述改善項目需要兩大心力，而這些技術撰寫人員十分寶貴。首先，請為每種隱含類型建立一個集中式「教學課程」頁面。這需要與核心開發人員團隊合作，找出一份具體類型清單，其說明文件對使用者來說極具價值 (通常是因為其中包含程式庫的強大隱藏功能，其說明文件目前只會出現在較難解決的教學課程中)。接著，針對每種隱含類型，我將不同的相關教學課程、API 文件和範例網頁統整成單一的權威說明文件來源，方便使用者連往該特定類型參照的任何位置。

當特定隱含類型的集中說明文件完成之後，第二項主要工作就是從現有 API 說明文件改為連結新說明文件的連結，並著重於簡化實際使用這些新說明文件的體驗，無論是使用 Python 內建 help() 公用程式或線上瀏覽說明文件的使用者。

雖然本文提供的說明文件格式可能會隨專案發展而改變，但我與 Matchartlib 核心團隊共同在每週的「開發人員呼叫」期間共同達成共識，我們提出的策略是最理解、實用且技術上最容易理解的方法 (對於這些呼叫「隱含類型」的說法)。我在為每種隱含類型建立集中式說明文件時，會使用現有的「教學課程」基礎架構，這樣就能輕鬆參照這些網頁，而無須建立任何新的公開類別 (同樣以 LineCollection 文件為例)：

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

我們日後，只要核心開發人員團隊同意將新的「類型」說明文件融入 Bona 修正 Python 類別 (例如我在 Mat chartlib Boostment Proposal 30) 中提議，我們就可以輕鬆變更這些參照的拼寫方式。

最後，我建議在本 Google 系列文件中記錄的隱含類型初始清單如下：

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors/lists of colors
  7. colornorm/colormap
  8. tick formatters

如需本文件的上線版本，請參閱我們的課程。