如何在reStructuredText的:param标签内格式化文档内容？

一、:param标签内的正确格式写法 #

在reStructuredText的参数文档中，要让示例和换行正常渲染，需严格遵循缩进层级和格式规范：

def your_function(mapper_matrix):
    """
    函数功能说明
    
    :param mapper_matrix:
        这是包含ref_col、ref_col_2和value列的查找表。
        
        **示例:**
        .. code-block:: python
            [("s1", "p1", "state1"),
             ("s1", "p2", special),
             ("s2", "p1", "state3"),
             ("s2", "p2", "state4")]
        
        任何缺失的映射都会在新列中生成空值。
    """
    # 函数逻辑
    pass

关键要点：

• :param标签后的所有说明内容，需比:param缩进至少4个空格
• 段落之间空一行来区分，不要用|强制换行
• 代码示例使用.. code-block:: python标记，且代码内容需再缩进一层（相对于code-block行）

二、换行与段落不显示的解决方案 #

1. 避免使用|或手动插入\n，reStructuredText通过空行分隔段落，同一段落内的连续文本会自动换行
2. 确保所有内容都处于:param标签的缩进范围内，超出缩进的内容会被识别为文档的其他部分，无法正常关联到参数说明

三、IntelliJ渲染器的兼容性问题 #

如果按照规范书写后仍无法正常渲染，大概率是IntelliJ的reStructuredText插件存在渲染bug：

• 先通过Sphinx官方工具生成HTML文档验证格式正确性：执行sphinx-build -b html docs/source docs/build，查看生成的页面是否正常显示
• 若官方渲染正常，可尝试更新IntelliJ的reStructuredText插件，或暂时用Sphinx预览替代

四、替代方案：将示例移至参数标签外 #

如果param内的格式始终存在渲染问题，可将示例放在函数主文档中，仅在param内做简要说明：

def your_function(mapper_matrix):
    """
    函数功能说明
    
    **查找表示例:**
    .. code-block:: python
        mapper_example = [("s1", "p1", "state1"),
                          ("s1", "p2", special),
                          ("s2", "p1", "state3"),
                          ("s2", "p2", "state4")]
    
    :param mapper_matrix: 包含ref_col、ref_col_2和value列的查找表，缺失映射会在新列产生空值。
    """
    # 函数逻辑
    pass

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