As explained in the Napoleon manual, using low-level ReStructuredText syntax in docstrings is a bad idea, as the docstrings will be effectively unreadable in plain text (e.g. when interactively exploring a package in IPython). Instead, Google style docstrings should be used, and rendered using the builtin Napoleon Sphinx extension. In this style, the docstring is organized using sections. There are only a small handful of shortcomings:

• The formatting of Attributes is less than ideal by default. It can be improved by setting napoleon_use_ivar = True in the Sphinx doc.py, but this also causes the section to be named "Variables" instead of "Attributes"
• It would be nice to distinguish (instance) attributes from class attributes, by allowing a "Class Attributes" section
• When documenting classes that have a dictionary interface, it would be nice to have a "Keys" section

The source code for the Napoleon extension is written in such a way that makes it easy to fix these annoyances. However, this would require forking the extension. Instead, we may patch it at runtime to achieve the desired behavior. Adding the following code in doc.py will achieve this:

# -- Extensions to the  Napoleon GoogleDocstring class ---------------------

# first, we define new methods for any new sections and add them to the class
def parse_keys_section(self, section):
return self._format_fields('Keys', self._consume_fields())

def parse_attributes_section(self, section):
return self._format_fields('Attributes', self._consume_fields())

def parse_class_attributes_section(self, section):
return self._format_fields('Class Attributes', self._consume_fields())