27.5. Google Style Docstrings#

The original reStructuredText style to define parameters with :param name: becomes a bit unreadable in plain text form. To make sure that the documentation is human readable also in plain text we recommend using Google style docstrings. Simply put, instead of writing

:param type1 name1: description 1
:param name2: description 2
:returns: return value description

you should write

Parameters:
  name1 (type1): description 1
  name2: description 2

Returns:
  return value description

The known sections you can and should use if appropriate are

  • Attributes

  • Example

  • Examples

  • Keyword Arguments

  • Methods

  • Note

  • Other Parameters

  • Parameters

  • Returns

  • Raises

  • References

  • See Also

  • Todo

  • Warning

  • Warns

  • Yields

You can see a more complete example of this format at http://www.sphinx-doc.org/en/stable/ext/example_google.html