如何在Google风格Python文档字符串中规范添加参考文献？

方法1：统一缩进对齐 #

Google风格文档字符串要求每个章节的内容与章节标题保持一致缩进（通常为4个空格），调整参考文献条目的缩进后，VS Code的格式化工具即可正确识别：

def viscosity(self) -> float: 
    """Live oil viscosity, cP    
    
    Return the live oil viscosity, cP.
    Requires pressure and temperature condition to previously be set.

    Args:
        None

    Returns:
        uoil (float): live oil viscosity, cP

    References:
        Fundamental Principles of Reservoir Engineering, B.Towler (2002) Page 23
        Correlations for Fluid Physical Property... Vasquez and Beggs (1980)
    """
    
    pabs = self._pressa  # absolute pressure
    temp = self.temp  # deg F
    oil_api = self.oil_api

（注：确保References下的每条引用都缩进4个空格，与Args、Returns内的内容对齐）

方法2：使用VS Code专用插件增强支持 #

安装支持Google风格文档字符串的插件，自动处理格式化逻辑：

• AutoDocstring：在插件设置中将autodocstring.docstringFormat设为google，它会自动生成规范的参考文献章节，并支持一键格式化。
• Python Docstring Generator：默认兼容Google风格，可识别并正确格式化References部分。

安装后重新编辑文档字符串，即可正常触发格式化。

方法3：自定义VS Code格式化配置 #

在VS Code的settings.json中添加以下配置，确保Python格式化工具（如autopep8、black）识别References章节：

{
    "python.formatting.provider": "autopep8",
    "python.docstringFormat": "google"
}

部分格式化工具默认忽略非标准章节，通过指定文档字符串格式为Google风格，可让工具正确解析并格式化References内容。

方法4：采用结构化引用格式 #

将参考文献改为编号式结构化格式，既方便工具识别，也提升可读性：

def viscosity(self) -> float: 
    """Live oil viscosity, cP    
    
    Return the live oil viscosity, cP.
    Requires pressure and temperature condition to previously be set.

    Args:
        None

    Returns:
        uoil (float): live oil viscosity, cP

    References:
        [1] Towler, B. (2002). Fundamental Principles of Reservoir Engineering, Page 23.
        [2] Vasquez, M., & Beggs, H. D. (1980). Correlations for Fluid Physical Property...
    """

内容的提问来源于stack exchange，提问作者Kaelin Ellis