Parameter texts are trimmed at newline in toc

[funkyfuture]

i have for example this docstring:

def ancestors(self, *filter: Filter) -> Iterator["TagNode"]:
    """
    :param filter: Any number of :term:`filter` s that a node must match to be
           yielded.
    :return: A :term:`generator iterator` that yields the ancestor nodes from bottom
             to top.

     :meta category: iter-relatives
    """

yet the resulting toc solely contains the text

ancestors(*filter)	param filter Any number of filter s that a node must match to be

and related, i don't think the keyworrd param is required in the toc. also, the return value's description should be included as well.

[kalekundert]

This is due to the way that .. autosummary:: formats things. Basically, the first sentence of the docstring is what gets used as the summary. In this case, that includes the :param: role, which ends up looking weird. I don't think autosummary is very configurable in this regard, so the best solution is probably just to add a brief summary before the :param: description, e.g.:

def ancestors(self, *filter: Filter) -> Iterator["TagNode"]:
    """
    Iterate through ancestor nodes after applying a filter.
    :param filter: Any number of :term:`filter` s that a node must match to be
           yielded.
    :return: A :term:`generator iterator` that yields the ancestor nodes from bottom
             to top.

    :meta category: iter-relatives
    """

[funkyfuture]

that isn't feasible in my case because it would introduce redundancies.

but i would be fine to omit the right column / to get a hyperlinked list instead of a table.

[kalekundert]

Hmmm, in that case, the two best options I can think of are:

• Overwrite Section._make_links() to modify the docstrings of the attributes being tabulated, to automatically generate nicer 1-sentence summaries for each one.

• Overwrite Section._make_links() to make the list of links yourself (e.g. not using autosummary). This wouldn't be trivial, but it'd give you complete control over the formatting of the list. If you do this, it's probably worth looking at the autosummary code, because you'll probably end up writing something similar.

[funkyfuture]

if i grasped it correctly, the table creation in autosummary wouldn't be changeable w/o re-implementing the whole extension. so i ended up hiding the contents with css. not nice, but effective.

the docs in question are much more usable now.