---
# System prepended metadata

title: Python / docs styles
tags: [Returns, docs, return_type, Raises, Google style, NumPy/SciPy style, Function, Python, ExceptionType, styles]

---

Python / docs styles
===
###### tags: `Python`
###### tags: `Python`, `docs`, `styles`, `NumPy/SciPy style`, `Function`, `Returns`, `return_type`, `Raises`, `ExceptionType`, `Google style`,

<br>

[TOC]

<br>

## 討論

### 常見的 docs styles
- ### Question
    參數描述應該是使用底下常見格式？
    ```
    ...
    parameters
    =========
    - param1: str
        <describe param1>
    - param2: str
        <describe param2>
    ```
    這是最常見的格式嗎？
- ### gpt-4o-2024-08-06
    你提到的格式接近於 **NumPy/SciPy** 文件風格，這種格式非常常見於科學計算相關的 Python 庫中，它的優點是簡潔明了，常用於 NumPy、SciPy 等專案。一般文件格式的幾種常見寫法如下：

    1. **NumPy/SciPy 風格**（你提到的格式屬於這種風格）：
       ```
       Function description

       Parameters
       ----------
       param1 : str
           Description of param1
       param2 : str
           Description of param2

       Returns
       -------
       return_type
           Description of return value

       Raises
       ------
       ExceptionType
           Description of raised exception (if any)
       ```

    2. **Google 風格**（另一個流行的風格）：
       ```
       Function description

       Args:
           param1 (str): Description of param1
           param2 (int): Description of param2

       Returns:
           return_type: Description of return value

       Raises:
           ExceptionType: Description of raised exception (if any)
       ```

    3. **Sphinx/ReST 風格**（Sphinx 文件系統常用的格式）：
       ```
       :param param1: Description of param1
       :type param1: str
       :param param2: Description of param2
       :type param2: int
       :return: Description of return value
       :rtype: return_type
       :raises ExceptionType: Description of raised exception
       ```

    其中 **NumPy/SciPy** 和 **Google 風格** 是目前最為流行的兩種。

    ### 你提到的格式：
    ```
    Function description

    Parameters
    ==========
    - param1 : str
        Description of param1
    - param2 : str
        Description of param2
    ```

    這個格式其實就是 **NumPy/SciPy 風格** 的簡化版本，少了 "Returns" 和 "Raises" 區段。完整的 NumPy/SciPy 風格會寫得更詳細一點，包括返回值、例外情況等。

    ### 小結
    根據實務經驗，**NumPy/SciPy 風格** 和 **Google 風格** 是最常見的兩種風格。如果你的專案沒有特別規定文件風格，選擇其中之一會是比較合適的做法。

    如果你想要保持一致性，可以根據團隊的文件風格要求來選擇 NumPy/SciPy 或 Google 風格。

- ### gpt-4o-2024-08-06 (in English)

    The format you mentioned is similar to the **NumPy/SciPy** style, which is widely used in Python libraries for scientific computing. It’s concise and clear, often seen in projects like NumPy and SciPy. Here are some common documentation formats:

    1. **NumPy/SciPy style** (the format you referred to falls under this style):
       ```
       Function description

       Parameters
       ----------
       param1 : str
           Description of param1
       param2 : str
           Description of param2

       Returns
       -------
       return_type
           Description of the return value

       Raises
       ------
       ExceptionType
           Description of the raised exception (if any)
       ```

    2. **Google style** (another popular format):
       ```
       Function description

       Args:
           param1 (str): Description of param1
           param2 (int): Description of param2

       Returns:
           return_type: Description of the return value

       Raises:
           ExceptionType: Description of the raised exception (if any)
       ```

    3. **Sphinx/ReST style** (commonly used in Sphinx documentation systems):
       ```
       :param param1: Description of param1
       :type param1: str
       :param param2: Description of param2
       :type param2: int
       :return: Description of the return value
       :rtype: return_type
       :raises ExceptionType: Description of the raised exception
       ```

    Among these, **NumPy/SciPy** and **Google style** are the most commonly used formats.

    ### The format you referred to:
    ```
    Function description

    Parameters
    ==========
    - param1 : str
        Description of param1
    - param2 : str
        Description of param2
    ```

    This format is essentially a simplified version of the **NumPy/SciPy style**, missing the "Returns" and "Raises" sections. The complete NumPy/SciPy style would typically include more details, such as return values and exceptions.

    ### Summary
    Based on common practice, **NumPy/SciPy style** and **Google style** are the two most widely used documentation styles. If your project doesn’t mandate a specific style, either would be a good choice.

    To maintain consistency, you can choose either NumPy/SciPy or Google style based on your team's documentation requirements.
