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 dos something** 中，以便将其加粗。 2) 编写一个自定义的 sphinx 扩展，它在 autodoc 解析文档字符串之前拦截它们，并相应地进行处理。

(我最终选择了选项 2，以便在我的文档字符串中包含节标题...这是该扩展的 source。它不满足您的需要，但它可能很有用一个起点，特别是 _remove_oneline 函数对模块文档字符串的作用)。