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