Sphinx与ReST：如何实现带列表的多行参数定义替换？

你可以通过在rst_prolog里编写完整的RST格式内容来保留多行带项目符号的描述，具体操作如下：

1. 在conf.py中配置替换规则 #

把原有的verbosity参数描述转换成符合RST语法的格式，写入rst_prolog，注意保持正确的缩进和换行：

rst_prolog = """
.. |verbosity| replace:: int, optional
    设置代码在控制台输出的反馈详细程度：

    • *0：静默模式*：除错误信息外，代码不会提供任何反馈。
    • *1：正常模式*（默认）：代码会提供必要的反馈，比如进度标记和当前执行步骤。
    • *2：详细模式*：代码会输出所有事件的相关信息。注意这可能会使输出杂乱，并减慢执行速度。
"""

2. 在函数docstring中引用替换标记 #

在所有需要使用该参数描述的地方，直接用|verbosity|代替重复的描述内容：

def example_function(arg1, verbosity=1):
    """示例函数

    参数:
        arg1: 示例参数
        verbosity: |verbosity|
    """
    # 函数逻辑

原理说明 #

Sphinx会将rst_prolog中的内容作为RST片段提前解析，只要替换内容遵循RST的语法规则（比如列表的项目符号、缩进层级），就能完整保留原有的多行结构和格式，不会被压缩成单段落。

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