Formatting multiline docstrings with Sphinx
-
27-06-2021 - |
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>
Solution
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).