NumPy 文件貢獻指南#

本指南將協助您決定要貢獻什麼，以及如何將其提交至官方 NumPy 文件。

文件團隊會議#

NumPy 社群已設定改善其文件的堅定目標。我們定期在 Zoom 上舉行文件會議（日期會在 numpy-discussion 郵件列表上公告），歡迎所有人參加。如果您有任何問題，或需要有人引導您完成最初的步驟，請與我們聯繫 – 我們很樂意提供協助。會議記錄會記錄在 hackmd.io 上，並儲存在 NumPy Archive 儲存庫中。

需要什麼#

NumPy 文件已涵蓋詳細資訊。API 參考文件是從程式碼中的 docstring 直接產生，當文件被 建置 時。雖然我們對於每個暴露給使用者的函式和類別都有大致完整的參考文件，但其中一些缺少使用範例。

我們缺乏的是範圍更廣的文件 – 教學、操作指南和解釋。回報錯誤是另一種貢獻方式。我們將討論這兩者。

貢獻修正#

我們渴望聽取並修正文件錯誤。但是為了處理最大的問題，我們最終不得不延遲或忽略一些錯誤報告。以下是要處理的最佳錯誤。

最高優先順序是技術上的不準確 – docstring 缺少參數、函式/參數/方法的不正確描述等等。其他「結構性」錯誤，如損壞的連結，也具有優先順序。所有這些修正都很容易確認和實施。如果您知道如何操作，可以提交一個包含修正的 Pull Request (PR)；否則請 開啟 issue。

錯字和拼字錯誤的優先順序較低；我們歡迎您告知這些錯誤，但可能無法立即修正。這些也可以作為 Pull Request 或 issue 處理。

明顯的措辭錯誤（例如遺漏「不」字）屬於錯字類別，但其他措辭修改 – 即使是語法 – 也需要判斷，這提高了門檻。請先以 issue 的形式提出修正，以測試水溫。

某些函式/物件，如 numpy.ndarray.transpose、numpy.array 等，在 C 擴充模組中定義，其 docstring 在 _add_newdocs.py 中單獨定義。

貢獻新頁面#

您在使用我們文件時遇到的挫折是我們了解需要修正什麼的最佳指南。

如果您撰寫遺失的文件，您就加入了開源的前線，但僅僅是讓我們知道缺少什麼，就是有意義的貢獻。如果您想撰寫文件，請將您的想法透過 郵件列表傳達，以獲得更多想法和回饋。如果您想提醒我們注意缺口，請 開啟 issue。請參閱 此 issue 以取得範例。

如果您正在尋找主題，我們正式的文件路線圖是NumPy 增強提案 (NEP)，NEP 44 — 重組 NumPy 文件。它指出我們文件需要協助的領域，並列出我們希望看到的幾個新增項目，包括 Jupyter Notebook。

文件框架#

撰寫有用的文件有其公式，四種公式幾乎涵蓋所有內容。有四種公式是因為文件分為四個類別 – tutorial、how-to guide、explanation 和 reference。文件以此方式劃分的洞察力歸功於 Daniele Procida 和他的 Diátaxis Framework。當您開始撰寫文件或提案時，請記住它將屬於這些類型中的哪一種。

NumPy 教學#

除了 NumPy 原始碼樹狀結構中包含的文件之外，您可以將 Jupyter Notebook 格式的內容提交到 NumPy 教學頁面。這組教學和教育材料旨在為 NumPy 專案提供高品質的資源，無論是自學還是課堂教學。這些資源在單獨的 GitHub 儲存庫 numpy-tutorials 中開發，您可以在其中查看現有的 Notebook、開啟 issue 以建議新主題，或將您自己的教學作為 Pull Request 提交。

更多關於貢獻#

如果英文不是您的母語，或者您只能提出粗略的草稿，請別擔心。開源是社群的努力。盡力而為 – 我們會協助修正問題。

圖片和真實生活中的資料使文字更具吸引力和力量，但請確保您使用的內容已獲得適當授權且可用。同樣地，即使是粗略的藝術作品想法也可以由其他人潤飾。

目前，NumPy 接受的資料格式僅限於其他 Python 科學函式庫（如 pandas、SciPy 或 Matplotlib）也使用的格式。我們正在開發一個套件以接受更多格式；請聯繫我們以了解詳細資訊。

NumPy 文件保存在原始碼樹狀結構中。若要將您的文件放入文件庫，您必須下載樹狀結構、建置它，並提交 Pull Request。如果您不熟悉 GitHub 和 Pull Request，請查看我們的 貢獻者指南。

我們的標記語言是 reStructuredText (rST)，它比 Markdown 更精細。Sphinx 是許多 Python 專案用來建置和連結專案文件的工具，它將 rST 轉換為 HTML 和其他格式。有關 rST 的更多資訊，請參閱 Quick reStructuredText Guide 或 reStructuredText Primer

間接貢獻#

如果您遇到外部材料，可以對 NumPy 文件有所助益，請透過 開啟 issue 告知我們。

您不一定要在此處貢獻才能為 NumPy 做出貢獻。如果您在您的部落格上撰寫教學、建立 YouTube 影片，或在 Stack Overflow 和其他網站上回答問題，您就已經做出了貢獻。

文件風格#

使用者文件#

  • 一般而言，我們的使用者指南遵循 Google 開發人員文件風格指南。

  • NumPy 風格規範適用於以下情況：

    • Google 沒有指南，或

    • 我們不喜歡使用 Google 風格規範

    我們目前的規則

    • 我們將 index 的複數形式定為 indices，而不是 indexes，遵循 numpy.indices 的先例。

    • 為了保持一致性，我們也將 matrix 的複數形式定為 matrices。

  • NumPy 或 Google 規則未充分解決的文法問題，由最新版本的 芝加哥風格手冊中關於「文法和用法」的章節決定。

  • 我們歡迎 提醒 我們應該添加到 NumPy 風格規則中的案例。

Docstring#

當結合 Sphinx 和 NumPy 慣例使用時，您應該使用 numpydoc 擴充功能，以便正確處理您的 docstring。例如，Sphinx 將從您的 docstring 中提取 Parameters 區段，並將其轉換為欄位列表。使用 numpydoc 也將避免純 Sphinx 在遇到 NumPy docstring 慣例（如區段標題 (例如 -------------)）時產生的 reStructuredText 錯誤，因為 sphinx 預期在 docstring 中找不到這些標題。

它可從以下位置取得：

請注意，對於 NumPy 內的文件，在範例開頭不需要執行 import numpy as np。

請使用 numpydoc 格式化標準，如他們的 範例 中所示。

文件化 C/C++ 程式碼#

NumPy 使用 Doxygen 來解析特殊格式的 C/C++ 註解區塊。這會產生 XML 檔案，這些檔案由 Breathe 轉換為 RST，供 Sphinx 使用。

完成文件化流程需要三個步驟:

1. 撰寫註解區塊#

雖然目前尚未設定要遵循的註解風格，但 Javadoc 比其他風格更受歡迎，因為它與目前現有的非索引註解區塊相似。

注意

請參閱 “文件化程式碼”。

以下是 Javadoc 風格的外觀:

/**
 * This a simple brief.
 *
 * And the details goes here.
 * Multi lines are welcome.
 *
 * @param  num  leave a comment for parameter num.
 * @param  str  leave a comment for the second parameter.
 * @return      leave a comment for the returned value.
 */
int doxy_javadoc_example(int num, const char *str);

以下是其呈現方式:

警告

doxygenfunction: 找不到檔案：/home/matti/oss/numpy/doc/build/doxygen/xml/index.xml

對於行註解，您可以使用三個斜線。例如:

/**
 *  Template to represent limbo numbers.
 *
 *  Specializations for integer types that are part of nowhere.
 *  It doesn't support with any real types.
 *
 *  @param Tp Type of the integer. Required to be an integer type.
 *  @param N  Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
 public:
    /// Default constructor. Initialize nothing.
    DoxyLimbo();
    /// Set Default behavior for copy the limbo.
    DoxyLimbo(const DoxyLimbo<Tp, N> &l);
    /// Returns the raw data for the limbo.
    const Tp *data();
 protected:
    Tp p_data[N]; ///< Example for inline comment.
};

以下是其呈現方式:

警告

doxygenclass: 找不到檔案：/home/matti/oss/numpy/doc/build/doxygen/xml/index.xml

常見 Doxygen 標籤：#

注意

如需更多標籤/命令，請查看 https://doxygen.dev.org.tw/manual/commands.html

@brief

開始一個段落，作為簡短描述。預設情況下，文件區塊的第一句話會自動被視為簡短描述，因為選項 JAVADOC_AUTOBRIEF 在 doxygen 設定中已啟用。

@details

就像 @brief 開始簡短描述一樣，@details 開始詳細描述。您也可以開始一個新段落（空行），這樣就不需要 @details 命令。

@param

開始描述函式參數，參數名稱為 <parameter-name>，後接參數的描述。將檢查參數是否存在，如果此參數（或任何其他參數）的文件遺失或未出現在函式宣告或定義中，則會發出警告。

@return

開始描述函式的傳回值。多個相鄰的 @return 命令將合併為一個段落。@return 描述在遇到空行或其他分節命令時結束。

@code/@endcode

開始/結束程式碼區塊。程式碼區塊的處理方式與普通文字不同。它被解釋為原始碼。

@rst/@endrst

開始/結束 reST 標記區塊。

範例#

請查看以下範例:

/**
 * A comment block contains reST markup.
 * @rst
 * .. note::
 *
 *   Thanks to Breathe_, we were able to bring it to Doxygen_
 *
 * Some code example::
 *
 *   int example(int x) {
 *       return x * 2;
 *   }
 * @endrst
 */
void doxy_reST_example(void);

以下是其呈現方式:

警告

doxygenfunction: 找不到檔案：/home/matti/oss/numpy/doc/build/doxygen/xml/index.xml

2. 饋送 Doxygen#

並非所有標頭檔都會自動收集。您必須在 Doxygen 的子設定檔中新增所需的 C/C++ 標頭路徑。

子設定檔具有唯一的名稱 .doxyfile，您通常可以在包含文件化標頭的目錄附近找到它。如果路徑接近（2 層深度）您要新增的標頭，但沒有設定檔，則需要建立新的設定檔。

子設定檔可以接受任何 Doxygen 設定選項，但不覆寫或重新初始化任何設定選項，而僅使用串連運算子「+=」。例如

# to specify certain headers
INPUT += @CUR_DIR/header1.h \
         @CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
              NPY_HAVE_FEATURE2

注意

@CUR_DIR 是一個範本常數，傳回子設定檔的目前目錄路徑。

3. 包含指示詞#

Breathe 提供了廣泛的自訂指示詞，以允許將 Doxygen 產生的文件轉換為 reST 檔案。

注意

如需更多資訊，請查看「指示詞 & 設定變數」

常見指示詞：#

doxygenfunction

此指示詞為單一函式產生適當的輸出。函式名稱在專案中必須是唯一的。

.. doxygenfunction:: <function name>
    :outline:
    :no-link:

查看 範例 以查看其實際運作。

doxygenclass

此指示詞為單一類別產生適當的輸出。它採用標準專案、路徑、輪廓和無連結選項，以及成員、受保護成員、私有成員、未文件化成員、成員群組和僅成員選項

.. doxygenclass:: <class name>
   :members: [...]
   :protected-members:
   :private-members:
   :undoc-members:
   :membergroups: ...
   :members-only:
   :outline:
   :no-link:

查看 doxygenclass 文件以取得更多詳細資訊並查看其實際運作。

doxygennamespace

此指示詞為命名空間的內容產生適當的輸出。它採用標準專案、路徑、輪廓和無連結選項，以及僅內容、成員、受保護成員、私有成員和未文件化成員選項。若要參考巢狀命名空間，必須提供完整的命名空間路徑，例如 foo::bar 表示 foo 命名空間內的 bar 命名空間。

.. doxygennamespace:: <namespace>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:

查看 doxygennamespace 文件以取得更多詳細資訊並查看其實際運作。

doxygengroup

此指示詞為 doxygen 群組的內容產生適當的輸出。可以使用來源註解中的特定 doxygen 標記宣告 doxygen 群組，如 doxygen 群組文件中所述。

它採用標準專案、路徑、輪廓和無連結選項，以及僅內容、成員、受保護成員、私有成員和未文件化成員選項。

.. doxygengroup:: <group name>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:
   :inner:

查看 doxygengroup 文件以取得更多詳細資訊並查看其實際運作。

舊版指示詞#

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

預設情況下，如果沒有任何引數使用，舊版指示詞將產生以下輸出

舊版

此子模組被視為舊版，將不再接收更新。這也可能表示它將在未來的 NumPy 版本中移除。

我們強烈建議您也新增自訂訊息，例如用於取代舊版 API 的新 API

.. legacy::

   For more details, see :ref:`distutils-status-migration`.

此訊息將附加到預設訊息，並產生以下輸出

舊版

此子模組被視為舊版，將不再接收更新。這也可能表示它將在未來的 NumPy 版本中移除。如需更多詳細資訊，請參閱 numpy.distutils 的狀態和遷移建議。

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

.. legacy:: function

這將產生以下輸出

舊版

此函式被視為舊版，將不再接收更新。這也可能表示它將在未來的 NumPy 版本中移除。

文件閱讀#

  • 技術寫作的主要組織 Write the Docs 舉辦會議、託管學習資源，並運行 Slack 頻道。

  • Google 的 技術寫作資源集合 說：「每位工程師同時也是作家」，其中包括為開發人員提供的免費線上課程，內容涵蓋文件規劃和撰寫。

  • Software Carpentry 的使命是向研究人員教授軟體。除了託管課程之外，該網站還說明如何有效地呈現想法。