The two formats are actually the same. This can be confusing but what's called the Info field lists can be considered the reST docstring syntax. If you look carefully at the version number it's been around since Sphinx version 0.4, next if we look at the current Sphinx change list it remits to a change list that predates version 1.0... The earliest mention there is:
Release 0.4 (Jun 23, 2008)
==========================
- Sphinx now interprets field lists with fields like
:param foo:in description units.
If we want to dig further back to the definition of the reST docstring syntax the archives of the Doc-SIG - Python Documentation Special Interest Group would be the way to go, but a good enough overview is given by PEP 256 - Rationale dated 01-Jun-2001. The document that emerged from then and is most frequently cited only makes a loose recommendation:
PEP 257 -- Docstring Conventions
Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line.
To summarize things, the reST docstring syntax consists simply of using reST Field Lists! (the NumPy and Google styles are just different styles of also writing reST Field Lists)!
Field List - reStructuredText Markup Specification
Field lists are mappings from field names to field bodies,
(...)
The interpretation of individual words in a multi-word field name is up to the application. The application may specify a syntax for the field name.
Syntax diagram (simplified):
+--------------------+----------------------+ | ":" field name ":" | field body | +-------+------------+ | | (body elements)+ | +-----------------------------------+
It's up to the application to specify the syntax of the field names; so what Sphinx documentation generator specifies for the 2 example syntaxes in the question is that they are equivalent (this does not necessarily hold if you change to a different documentation generator).
Answer from bad_coder on Stack OverflowStupid Q: class docstring reStructuredText guide?
What format do you use for your docstrings?
Which docstring format do you prefer?
What is the "working" Python docstring style for VS Code tooltips?
The two formats are actually the same. This can be confusing but what's called the Info field lists can be considered the reST docstring syntax. If you look carefully at the version number it's been around since Sphinx version 0.4, next if we look at the current Sphinx change list it remits to a change list that predates version 1.0... The earliest mention there is:
Release 0.4 (Jun 23, 2008)
==========================
- Sphinx now interprets field lists with fields like
:param foo:in description units.
If we want to dig further back to the definition of the reST docstring syntax the archives of the Doc-SIG - Python Documentation Special Interest Group would be the way to go, but a good enough overview is given by PEP 256 - Rationale dated 01-Jun-2001. The document that emerged from then and is most frequently cited only makes a loose recommendation:
PEP 257 -- Docstring Conventions
Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line.
To summarize things, the reST docstring syntax consists simply of using reST Field Lists! (the NumPy and Google styles are just different styles of also writing reST Field Lists)!
Field List - reStructuredText Markup Specification
Field lists are mappings from field names to field bodies,
(...)
The interpretation of individual words in a multi-word field name is up to the application. The application may specify a syntax for the field name.
Syntax diagram (simplified):
+--------------------+----------------------+ | ":" field name ":" | field body | +-------+------------+ | | (body elements)+ | +-----------------------------------+
It's up to the application to specify the syntax of the field names; so what Sphinx documentation generator specifies for the 2 example syntaxes in the question is that they are equivalent (this does not necessarily hold if you change to a different documentation generator).
Thanks to @mzjin's answer in the comments: this link describes that it is possible since v0.4.
The below example is given in the link, which is exactly what I was looking for.
py:function:: send_message(sender, recipient, message_body, [priority=1])
"""
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
"""
I'd like to find a good guide on how to format class docstrings in reStructuredText. Using PyCharm and can't figure it out on my own, the formatting is somehow off and the context menu action doesn't help.