Python / docs 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.