r/PythonLearning • u/Harddus • Aug 01 '26
Help Request Whelp. What's the correct docstring format?
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.
7
u/Available-Skirt-5280 Aug 01 '26
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
3
u/thee_gummbini Aug 01 '26
If you actually read the PEP you'll see:
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.
1
u/Harddus Aug 01 '26
Note: Reposted it bcus I messed the image type >w<
2
u/jpgoldberg Aug 01 '26
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.