為 Python 程式碼新增文件

Python 的文件透過 docstring 提供，並使用 Sphinx 產生。請參考 Google 樣式的 Python docstring 指南，以取得 docstring 格式範例。

請依照下列指示來記錄、產生和發布新的 Python docstring

1. 將 docstring 直接新增至目標方法名稱下方。至少請新增下列項目的描述：

   • 方法的功能行為

   • 引數，以 Args 區段表示

   • 傳回值，以 Returns 區段表示

   • 可能擲回的例外狀況 (如果適用)，以 Raises 區段表示

   其他區段，例如 Todo、Note 和 Example，應視需要新增。

   以下是 Python docstring 範例

   def example_method(alignment: c_size_t, param: float) -> int:
       """
       This class is an example of how you can write docstrings.
       You can add multiple lines of those descriptions. Make sure to include
       useful information about your method.
   
       **Code Example:**
   
       .. code-block:: cpp
   
           // Here is a C++ code block
           std::vector<int32_t> foo(const std::vector<int32_t> &lst) {
               std::vector<int32_t> ret;
               for (const auto x : lst) {
                   ret.emplace_back(x * 2);
               }
               return ret;
           }
   
       And here is a verbatim-text diagram example:
   
       .. code-block:: text
   
           .------+---------------------------------.-----------------------------
           |            Block A (first)             |       Block B (second)
           +------+------+--------------------------+------+------+---------------
           | Next | Prev |   usable space           | Next | Prev | usable space..
           +------+------+--------------------------+------+--+---+---------------
           ^  |                                     ^         |
           |  '-------------------------------------'         |
           |                                                  |
           '----------- Block B's prev points to Block A -----'
   
       Todo:
           * This is a TODO item.
           * And a second TODO item.
   
       Args:
           alignment (c_size_t): Description of the `alignment` value.
           param (float): Description of `param1`.
   
       Returns:
           Description of the method's return value.
   
       Raises:
           AttributeError: If there is an error with the attributes.
           ValueError: If `param` is equal to 3.14.
   
       Example:
           This is how you can use this function
   
           >>> print("Code blocks are supported")
   
       Note:
           For more info on reStructuredText docstrings, see
           `here <https://sphinx-doc.dev.org.tw/en/master/usage/restructuredtext/basics.html>`__
           and
           `here <https://peps.python.org/pep-0287/>`__.
       """
       return 42
   
   
   

2. 在 Sphinx 文件方面，將 autofunction 指令新增至對應的 .rst 檔案。如果對應的 Python 原始碼檔案沒有 .rst 檔案，請建立一個與 Python 原始碼檔案同名的新檔案。以上述範例為例

   .. autofunction:: fbgemm_gpu.docs.examples.example_method
   

3. 請確認 .rst 檔案已包含在 index.rst 中的 toctree 中 (例如 fbgemm-gpu.toc.api.python)。

4. 透過在本機端使用 建置文件 建置文件，或提交 PR 以取得 Netlify 預覽，來驗證變更。

---

上述 Python docstring 範例會產生下列 HTML 輸出

fbgemm_gpu.docs.examples.example_method(alignment: c_ulong, param: float) → int

此類別示範如何撰寫 docstring。您可以新增多行描述。請務必包含關於您方法的實用資訊。

程式碼範例

// Here is a C++ code block
std::vector<int32_t> foo(const std::vector<int32_t> &lst) {
    std::vector<int32_t> ret;
    for (const auto x : lst) {
        ret.emplace_back(x * 2);
    }
    return ret;
}

以下是逐字文字圖表範例

.------+---------------------------------.-----------------------------
|            Block A (first)             |       Block B (second)
+------+------+--------------------------+------+------+---------------
| Next | Prev |   usable space           | Next | Prev | usable space..
+------+------+--------------------------+------+--+---+---------------
^  |                                     ^         |
|  '-------------------------------------'         |
|                                                  |
'----------- Block B's prev points to Block A -----'

待辦事項

• 這是一個待辦事項。

• 以及第二個待辦事項。

參數:

• alignment (c_size_t) – alignment 值的描述。

• param (float) – param1 的描述。

傳回:

方法傳回值的描述。

引發:

• AttributeError – 如果屬性發生錯誤。

• ValueError – 如果 param 等於 3.14。

範例

以下是如何使用此函數

>>> print("Code blocks are supported")

注意

如需關於 reStructuredText docstring 的更多資訊，請參閱這裡和這裡。

---

為自動產生的 Python 程式碼新增文件

許多 FBGEMM_GPU Python API 方法都是在建置過程中透過 PyTorch 自動產生的，而且需要在事後附加 docstring。請依照下列指示來記錄自動產生的 Python 方法

1. 如果需要，請在存放庫中的 fbgemm_gpu/fbgemm_gpu/docs 下建立 Python 檔案。

2. 在 Python 檔案中，使用 fbgemm_gpu.docs.common 中提供的協助程式方法，依方法名稱將 docstring 附加至目標自動產生方法。以下是程式碼庫中的範例

   import torch
   
   from .common import add_docs
   
   
   add_docs(
       torch.ops.fbgemm.jagged_2d_to_dense,
       """
   jagged_2d_to_dense(values, x_offsets, max_sequence_length) -> Tensor
   
   Converts a jagged tensor, with a 2D values array into a dense tensor, padding with zeros.
   
   Args:
       values (Tensor): 2D tensor containing the values of the jagged tensor.
   
       x_offsets (Tensor): 1D tensor containing the starting point of each jagged row in the values tensor.
   
       max_sequence_length (int): Maximum length of any row in the jagged dimension.
   
   Returns:
       Tensor: The padded dense tensor
   
   Example:
       >>> values = torch.tensor([[1,1],[2,2],[3,3],[4,4]])
       >>> x_offsets = torch.tensor([0, 1, 3])
       >>> torch.ops.fbgemm.jagged_2d_to_dense(values, x_offsets, 3)
       tensor([[[1, 1],
                [0, 0],
                [0, 0]],
               [[2, 2],
                [3, 3],
                [0, 0]]])
   
   """,
   )
   

3. 如果 fbgemm_gpu/fbgemm_gpu/docs/__init__.py 中的匯入清單中尚未出現 Python 檔案，請將其附加至清單中。這會強制在載入 fbgemm_gpu 模組時載入特設文件。例如

   from . import the_new_doc_module
   

4. 請依照 為 Python 程式碼新增文件 中的剩餘步驟，在文件中呈現 docstring。