為 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://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
           and
           `here <https://peps.python.org/pep-0287/>`__.
       """
       return 42
   
   
   

2. 在 Sphinx 文件端，向相應的 .rst 檔案新增一個 autofunction 指令。如果對應的 Python 原始檔沒有 .rst 檔案，請建立一個與 Python 原始檔同名的新檔案。使用上述示例：

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

3. 確保 .rst 檔案包含在 index.rst 的 toctree 中（例如 FBGEMM_GPU Python API）。

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) – param 的描述。

返回值：

方法返回值的描述。

丟擲：

• 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. 如果不存在，將 Python 檔案附加到 fbgemm_gpu/fbgemm_gpu/docs/__init__.py 的匯入列表中。這將強制在載入 fbgemm_gpu 模組時載入臨時文件。例如：

   from . import the_new_doc_module
   

4. 按照 為 Python 程式碼新增文件 中的剩餘步驟，在文件中渲染 docstring。