Sphinx：避免字典类型参数描述换行生成新段落

问题描述 #

使用Sphinx结合Napoleon扩展（启用Numpy风格文档字符串）为接收字典参数的函数编写文档时，参数描述里的“Settings dictionary with keys:”会被渲染成独立段落，无法与settings的类型说明（dict）处于同一段。

解决方案 #

调整文档字符串格式，移除“Settings dictionary with keys:”后的空行，让字典键的定义列表直接承接在这句话之后，保持缩进一致。修改后的代码如下：

def demoFunction(settings):
    """Some description

    Parameters
    ----------
    settings : `dict`
        Settings dictionary with keys:
        ``"color"``
            Hex colour code (`str`).
        ``"size"``
            Point area in pixels (`float`).
        ``"complicatedKey"``
            A key with a complicated description. Like any definition list item,
            the content can be wrapped. You can include lists inside the item as well:

            - The first item of the list. Lorem ipsum dolor sit amet, consectetur
              adipiscing elit.

            Proin nulla magna, egestas quis nisi id, dictum mollis diam. Duis lorem
            eros, tempor egestas ligula eget, dapibus posuere justo.

            - The second item of the list.

            You can also include multiple paragraphs in a key's description. Ensure that
            all content is aligned with the opening content line.
    """
    return False

原理说明 #

Napoleon扩展解析Numpy风格文档时，会将参数描述中空行后的内容识别为新段落。移除空行后，“Settings dictionary with keys:”会被视为参数类型说明的延续内容，与settings : dict合并为同一段落，后续的字典键定义列表则作为该段落的嵌套内容正常渲染。

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