python - 使用 Sphinx 格式化多行文档字符串

Question

使用sphinx autodoc，有没有办法以特殊方式格式化多行文档字符串的第一行？

考虑：

def whatever():
    """This function does something.

    This really should have a full function definition, but I am too lazy.
    Some more stuff.
    """

生成的html代码：

<dd>
<p>This function does something.</p>
<p>This really should have a full function definition, but I am too lazy. Some more stuff.</p>
</dd>

我希望它是这样的：

<dd>
<p class='headline'>This function does something.</p>
<p>This really should have a full function definition, but I am too lazy. Some more stuff.</p>
</dd>

Answer 1

据我所知，autodoc 并没有为您提供很多标记文档字符串的能力，尤其是在向文档字符串添加自定义样式方面。我能想到有两种方法可以解决这个问题：1）将第一行**This function does something**换成粗体。2) 编写一个自定义 sphinx 扩展，在 autodoc 解析文档字符串之前拦截它们，并相应地处理它们。

（我最终走上了选项 2 的道路，以便在我的文档字符串中包含部分标题......这是该扩展名的来源。它不能满足您的需求，但它可能作为起点很有用，特别是该_remove_oneline函数对模块文档字符串的作用）。