Force sphinx autosummary to display the first line after the heading in module docstrings in modules' summary table

Question

For classes/functions, sphinx's autosummary extension can generate a nice table summarizing the list of available classes/functions in a particular module, such that the first column consists a list of these items, and the second column consists of the first line taken from class/function docstrings as description (see below).

---

---

Likewise, if I have a module that itself contains several submodules, autosummary can also generate a similar summary table (see below).

---

---

But, as you can see, the description (i.e., the second column) in this case is simply the module's heading. For instance, in this example, the solvers.py module looks like:

"""
Solvers
=======
Brief description of 'Solvers'!
"""
...

My question is: how can I tell sphinx.autosummary to display the first line (after the heading) from the module's docstrings as the description in the summary table? For instance, in this case, I'd want autosummary to display "Brief description of 'Solvers'!" in the second column for solvers module.

Many thanks!

Answer 1

Recently I've encountered the same issue and (in case someone's still interested), solved it.
I created a simple solution for python library function patching. This solution can be used to patch this (and some other) Sphinx functions.

For this example the patching code will be:

from sphinx.ext.autosummary import extract_summary
from patcher import wrap_source_function


def extract_summary_wrapper(func):
    return lambda doc, document: func(doc, document).split("\n\n")[-1]


if __name__ == "__main__":
    wrap_source_function(extract_summary, extract_summary_wrapper)

The patcher is the patcher file from the gist.

NB! This code snippet should be executed at least once (but can be executed each time) before sphinx-build command!

Cheers!