python-sphinx：格式化多行文档字符串

使用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>

解决方法:

据我所知,autodoc并没有为您提供很多标记文档字符串的功能,尤其是在向文档字符串添加自定义样式方面.我可以考虑以下两种方法来解决此问题：1)将第一行包装在**此函数执行某些操作**中,因此将其加粗. 2)编写一个自定义的sphinx扩展名,该扩展名在autodoc解析文档字符串之前将其截取,并相应地处理它们.

(我最终走上了选择2的道路,以便在我的文档字符串中包含节标题…这是该扩展名的source.它不能满足您的需要,但可能作为一个起点很有用,尤其是_remove_oneline函数对模块文档字符串的作用).

标签：python-sphinx,python,documentation
来源： https://codeday.me/bug/20191127/2076748.html