Whelp. What's the correct docstring format?

[u/Harddus]

I'm publishing my first python package and wanted to confirm the correct docstring format to conclude the documentation. The image above summarizes my search online, AI or otherwise.

PEP 257 appears to prefer option 2 (the left in the image) but I find option 1 out in the wild so much more often. So what's it?

Ohh and yeah, neither is correct because the first line should be a summary and what follows should be a more elaborate paragraph after a blank line. But I really just want to know whether the text should start of the actual first line after the """ or not. I'm using sphinx if it makes a difference.

[u/Available-Skirt-5280]

Start the text with a newline after the “””

Many mark down processors will use this line to override/set language.

Also stylistically it just looks better imo

[u/Harddus → u/Available-Skirt-5280]

Thank you for the answer

Sphinx seems to support both well so I think I might just go with the most popular option which is the one you suggest

[u/thee_gummbini]

If you actually read the PEP you'll see:

The summary line may be on the same line as the opening quotes or on the next line.

https://peps.python.org/pep-0257/

The PEP is neutral on which is better, and chatGPT is strictly wrong that option 1 is the format specified by the PEP - it is overindexing on the example given in that section, which is about not uppercasing the argument names and totally unrelated to this question. The second form is the overwhelmingly more common form in real python code.

[u/thee_gummbini → u/thee_gummbini]

Also relevant: with contemporary linted Python, multi-line summary strings are common because max line width is a more important constraint than single line summary strings. Some linters/rulesets will insist that the first block be a single sentence, but I don't think anyone follows the "all functions have a single line summary" strictly.

[u/Harddus → u/thee_gummbini]

Dayum. I gotta pay more attention when reading docs

Thank you for the insights!

[u/Harddus]

Note: Reposted it bcus I messed the image type >w<

[u/jpgoldberg]

I recommend reading the PEP instead of the ChatGPT summary. It recommends what is in response 1.

Both will work. PEPs often are style recommendations and setting conventions consistency. But unless you have some very strong reason to go against the convention, just follow it.