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 OverflowThe 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
"""
After looking through the source and experimenting - here is how to do it in Sphinx 1.1.
In your conf.py file create a new MethodDocumenter subclass. Here you can set a new "objtype", make sure the docstring is not indented, and remove the title.
from sphinx.ext import autodoc
class SimpleDocumenter(autodoc.MethodDocumenter):
objtype = "simple"
#do not indent the content
content_indent = ""
#do not add a header to the docstring
def add_directive_header(self, sig):
pass
Then make sure this is added to the available documenters with the following function (again in conf.py):
def setup(app):
app.add_autodocumenter(SimpleDocumenter)
Then when you just want to display a method's docstring use the following format in your .txt or .rst files. Just prefix your objname with auto.
.. autosimple:: mod.MyClass.my_method
I used this approach with Sphinx 5.3.
If you don't want to override the default MethodDocumenter for your class API documentation, you need to also override the following can_document_member and set it to False. The resulting class looks as follows
class SimpleDocumenter(autodoc.MethodDocumenter):
"""
Reference a class or method docstring only.
see https://stackoverflow.com/a/7832437/5726546
"""
objtype = "simple"
content_indent = ""
@classmethod
def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
return False
# do not add a header to the docstring
def add_directive_header(self, sig: str) -> None:
pass
Setup and directive are the same as in the answer by geographika.