Sphinx 文档和重构文本：多行参数定义的替换

Question

我正在用 Python 开发一个具有数百个函数的项目。其中很多都有一个名为

verbosity

的参数，我对其进行了如下描述：

"""
verbosity: int, optional
    Sets how much feedback the code will provide in the console output:

    • *0: Silent mode.* The code won’t provide any feedback, apart from error messages.
    • *1: Normal mode* (default). The code will provide essential feedback such as progression markers and
      current steps.
    • *2: Chatty mode.* The code will provide all possible information on the events happening. Note that this
      may clutter the output and slow down the execution.
"""

当这个参数到处弹出时，我想用替换来替换基本的复制/粘贴。我看到可以通过在conf.py文件中设置

rst_prolog

参数来实现，如：

rst_prolog = """
.. |verbosity| replace:: description
"""

但是，以这种方式定义替换似乎只允许“描述”仅包含一个段落。知道如何保留带有我已有的要点的文本吗？

谢谢！

Answer 1

是的，替换替换仅适用于单个段落（但是，可能跨越多行）。

您可以将更长或更复杂的源代码片段保存到文件中，并使用 “include”指令插入它们。