How to make line breaks in long function signature and format it prettily in Sphinx autodoc

Question

I have a function with a long signature with type hint, like

def set_parameters(
        tokenizer: Union[None, "Tokenizer", str] = None,
        vocab: Optional["Vocab"] = None,
        vocab_from: Optional[Dict[str, str]] = None,
        max_sent_length: Optional[int] = None,
        max_turn_length: Optional[int] = None,
        convert_to_lower_letter: Optional[bool] = None,
        weak=False) -> "FieldContext":

I use Sphinx autodoc to generate docstring.

.. autofunction:: set_parameters

Then, Sphinx will ignore the line break and describe the function in one line.

set_parameters(tokenizer: Union[None, Tokenizer, str] = None, vocab: Optional[Vocab] = None, vocab_from: Optional[Dict[str, str]] = None, max_sent_length: Optional[int] = None,    max_turn_length: Optional[int] = None, convert_to_lower_letter: Optional[bool] = None, weak=False) -> FieldContext:

It's very ugly and hard to read. What I want is either it follows the line breaks in my code or do some line breaks itself automatically. Is there any way to realize?

Cripps

I don't think there is an easy way to do this. See github.com/sphinx-doc/sphinx/issues/1514 – Adeleadelheid

Great, I'll try to find helps there – Cripps

Answer 1

A quick and dirty option would be to use CSS:

dl.class > dt > em:before {
    content: ' ';
    display: block;
}

It's not perfect or pretty, but it at least puts the arguments into a list that is easier to visually scan.

Spinode

Thanks, it works but not pretty. But you inspire me to do some tricks in html. – Cripps

See this comment on the Sphinx issue tracker instead, which provides substantially prettier output. – Crossgrained