如何在docstring中提及函数参数并保持Sphinx样式一致？

常规简单方案：反引号包裹参数名 #

直接用反引号`参数名`包裹要提及的参数，这是Python docstring中提及标识符的通用做法，Sphinx渲染后会自动生成和函数签名、:param块中参数一致的等宽样式，无需额外配置，单文件内统一使用即可。示例：

def process_data(input_list, output_path):
    """处理输入数据并写入指定路径。

    此函数会遍历`input_list`中的元素，将结果写入`output_path`。
    注意：`input_list`不能为空。
    """
    pass

基于Sphinx标记的方案：:data:标记 #

你之前尝试的:data:标记完全可行，Sphinx默认会将其渲染为等宽样式，和参数签名、:param中的参数视觉统一。如果习惯用Sphinx的标记语法，单文件内统一使用该标记即可。示例：

def process_data(input_list, output_path):
    """处理输入数据并写入指定路径。

    此函数会遍历`:data:`input_list``中的元素，将结果写入`:data:`output_path``。
    注意：`:data:`input_list``不能为空。
    """
    pass

不推荐的方案：:paramref:标记 #

:paramref:主要用于跨文件的参数引用，如果你不需要跨文件跳转，仅在单文件内提及参数，使用它反而冗余，没必要额外配置。

内容的提问来源于stack exchange，提问作者Jeffrey Goldberg