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

Question

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

3

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

- georg

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Eli Collins · Accepted Answer

据我所知，autodoc在标记docstrings方面的能力非常有限，特别是在添加自定义样式到docstring方面。我能想到两种方法来解决这个问题：1）将第一行用**This function does something**包裹起来，以使其加粗显示。2）编写一个自定义的sphinx扩展程序，在autodoc解析docstrings之前拦截docstrings并相应地处理。

（我最终选择了第二种方法，以便在我的docstrings中有节标题... 这是该扩展的源代码。它不会满足你的需求，但作为一个起点可能很有用，尤其是_remove_oneline函数对模块docstrings的处理方式）。