Utilizing Sphinx with reStructuredText formatted docstrings

user_3909896 0
Viewed 460

According to the writing docstrings tutorial of Sphinx, it is possible to utilize Sphinx's autodoc extension to automatically generate documentation. We can either write docstring with the Sphinx format, Google or Numpy (the latter two with the napoleon extension).

Is it possible to write docstrings in reStructuredText format?

e.g.:

"""[Summary]

Extended description of function.

:param int arg1: Description of arg1.
:param str arg2: Description of arg2.
:raise: ValueError if arg1 is equal to arg2
:return: Description of return value
:rtype: bool
"""

For comparison, this is Sphinx native format:

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

Comparison of docstrings

docstring restructuredtext python-sphinx python
2 Answers

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
   """
user_39098960

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).

user_107940310
Related