Matplotlib 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
Matplotlib
技術撰稿人：
brunobeltran
專案名稱：
透過標準化「隱含」類型的說明文件，提升功能的發現率
專案長度：
長時間放送 (5 個月)

Project description

動機

過去，matchartlib 的 API 大量依賴字串即列舉的「隱含類型」。除了模仿 Matlab 的 API 之外，這些參數字串可讓使用者將含有語意豐富的值做為引數，傳遞到 matDrawlib 函式中，而不必明確匯入或詳細為實際列舉值加上前置字串 (例如，plt.plot(x, y, linestyle='solid') 較容易輸入，而且較不多餘，例如 plt.plot(x, y, linestyle=mpl.LineStyle.solid))。

因為有許多字串即列舉隱含類型，已發展出更複雜的特徵。舉例來說，linestyle 現在可以是字串或序列的 2 元組，而 MarkerStyle 則可以是字串或 matplotlib.path.Path。雖然許多隱含類型都是如此，但根據我所知，只有 MarkerStyle 處於已升級為適當的 Python 類別的狀態。

由於這些隱含類型本身並非類別，因此 Matplotlib 必須在過去推出自己的解決方案，以便集中記錄和驗證這些隱含類型 (例如 docstring.interpd.update 文字說明間接法模式和 cbook._check_in_list 驗證器模式)，而非使用 Python 類別提供的標準工具鍊 (例如文字說明和驗證-at-__init__ 模式)。

雖然這些解決方案對我們來說相當實用，但由於缺乏明確的位置可用於記錄每個隱含型別，因此說明文件通常很難找到，允許值的大型表格會在整個說明文件中重複出現，而且說明文件通常完全缺少隱含型別的範圍明確陳述。以 plt.plot 說明文件為例：在「附註」中，類似 Matlab 的格式字串樣式方法說明提到 linestyle、color 和 markers 選項。除了上述提示之外，還有許多其他方式可以傳遞這三個值，但對許多使用者來說，這就是他們唯一能瞭解這些選項可能值的來源，除非他們偶然發現相關的教學課程。我們在文件中加入了 Line2D 屬性的表格，希望向讀者展示可用來控制情節的選項。不過，雖然 linestyle 項目可順利連結至 Line2D.set_linestyle (需要兩次點擊)，並說明可能的輸入內容，但 color 和 markers 項目則無法做到這點。color 只是連結至 Line2D.set_color，無法提供任何關於允許哪些類型輸入內容的直覺資訊。

有人認為，只要整理出造成問題的個別 docstring，就能解決這個問題，但很遺憾，這個問題比這更系統化。如果無法集中查看說明文件，這只會導致我們在每個隱含類型使用中，重複的說明文件副本越來越多，因此新手較難直接找到需要的參數。不過，現行系統會強制使用者透過 Wiki 瀏覽方式，逐一瀏覽我們的文件，或從 Stack Overflow 範例中逐一瀏覽，慢慢拼湊出各個隱含型別的概念模型，這麼做也無法永續。

結束目標

理想情況下，任何提到隱含類型的內容都應連結至單一頁面，說明該類型可採用的所有可能值，並依從最簡單和常見的順序排列，到最進階或不常見的順序排列。我們可以利用頂層 API 說明文件中的寶貴視覺空間，逐一列舉特定參數的所有可能輸入類型，然後使用相同的空間，以平實的文字說明參數要控制的繪圖抽象化內容。

再次使用 linestyle 範例，LineCollection 文件中需要的內容如下：

  1. 可允許輸入的完整文件連結 (Line2D.set_linestyle 和linestyle 教學課程中的組合)。
  2. 以簡單的文字說明參數的用途。對於 matplotlib 的進階使用者來說，這點從參數名稱中即可看出，但對於新使用者來說，不一定是這樣。

在實際的 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 解析，以便指向單一權威且完整的說明文件組合，說明 Matplotlib 如何處理線條樣式。

優點

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

  1. 在純文字中清楚顯示每個函式的完整功能 (無須點按)。
  2. 讓預設選項顯示 (無需點按)。只要看到預設選項，通常就足以喚起回訪使用者的記憶。
  3. 完整說明參數的「最常見」和「最簡單」選項，讓使用者在瀏覽時輕鬆取得 (只要按一下即可)。
  4. 讓使用者只要輕鬆「向下捲動」即可發現更多強大的功能和輸入法，且只需點按一次即可查看進階選項。
  5. 提供集中式策略，將頂層「API」說明文件連結至相關「教學課程」。
  6. 避免 API 說明爆炸，因為掃描每個參數的許多可能選項會導致個別 docstring 難以使用。

相較於目前的文件，這種做法還有其他優點：

  1. 但文件採集中化的方式，較不容易過時。
  2. 目前必須讀取程式碼才能學習的許多 matchartlib「隱含標準」(例如「邊界」與「極端」的正規化)。
  3. 這個程序會以更容易透過 GitHub 問題追蹤器追蹤的方式，突顯 API 一致性問題，協助改善 API。
  4. 由於需要剖析的文字量大幅減少，因此文件建構時間縮短。

實作

如要實施上述改善措施，需要專責技術撰寫人員的協助，第一個是為每個隱含類型建立一個集中式「教學課程」頁面。這需要與核心開發團隊合作，找出具體的隱含類型清單，這些隱含類型的說明文件對使用者來說相當實用 (通常因為其中的強大隱藏功能，其說明文件目前只適用於難以理解的教學課程)。針對每個隱含類型，我會將各種相關教學課程、API 說明文件和範例頁面整合成單一權威說明文件來源，並連結至任何引用該特定類型的網頁。

一旦完成特定隱含型別的集中說明文件，就會開始進行第二項重大工作：將現有的 API 說明文件替換為新說明文件的連結，讓使用者能盡可能輕鬆地使用這份新說明文件，無論是使用 Python 內建 help() 公用程式，還是在線上瀏覽說明文件的使用者皆然。

雖然這裡提議的確切格式可能會隨著本專案演進而改變，但我在每週「開發呼叫」期間，與 Matmarklib 核心團隊合作，希望就此處提議的策略是最簡單、最實用，在技術層面上最容易追蹤的方法 (記錄這些「隱含類型」的附註)。我會在初始階段使用現有的「教學課程」基礎架構，為每個隱含類型建立集中式說明文件，讓我可以輕鬆參照這些頁面，而無須建立任何新的公開類別 (再次以 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`.
""""""

往後，只要核心開發團隊同意將新的「類型」說明文件納入真正的 Python 類別的最佳長期策略，我們就能輕鬆變更這些參照的拼寫方式，例如我在 Matplotlib 改善提案 30 中提出的建議。

最後，我提議在本季 Google 文件季期間 記錄的隱含類型清單如下：

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

您可以前往Discourse 查看本文件的最新版本。