I'd have a question on the style guide for Python docstrings provided by Sphinx. For example, the answer with the highest vote in this post gives this suggestion:
def send_message(sender, recipient, message_body, priority=1) -> int:
"""
Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
"""
However, what would we be the style guide if we needed a longer explanation for one of the parameters? For example:
def send_message(sender, recipient, message_body, priority=1) -> int:
"""
Send a message to a recipient
:param str sender: The person sending the message from Lyon to Paris via a rerouting in Marseille
:param str recipient: The recipient of the message
"""
It's a silly example, but since PEP8 recommends at most 79 (or even 72 for docstring) character-lines, I'm not quite sure how to split it. Is this recommended?
def send_message(sender, recipient, message_body, priority=1) -> int:
"""
Send a message to a recipient
:param str sender: The person sending the message from Lyon
to Paris via a rerouting in Marseille
:param str recipient: The recipient of the message
"""
