使用 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函數對模塊文檔字符串做了什么）。