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

Question

Using sphinx autodoc , is there a way to format a first line of a multiline docstring in a special way?

Consider:

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

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

The html code being generated:

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

I want it to be something like:

<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

To my knowledge, autodoc doesn't give you very many abilities to mark up the docstrings, especially with regards to adding custom styling to the docstring. There's two ways to get around this I can think of: 1) wrap the first line in **This function does something** so it'll be bolded. 2) write a custom sphinx extension which intercepts the docstrings before autodoc has parsed them, and mangle things accordingly.

(I ended up going down the road of option 2 in order to have section headers in my docstrings... here's the source for that extension. It doesn't do what you need, but it might be useful as a starting point, particularly what the _remove_oneline function does to module docstrings).