I've been reading through Numpy's documentation standards, and it doesn't seem to make a mention of object attributes - only class attributes.
So, for instance, how would I document the following?
class ClassA(object):
"""Short description of ClassA
Long description of ClassA
Parameters
----------
param : param_type, optional
param_description
Attributes (class)
----------
class_attr : class_attr_type
class_attr_description
Attributes (object)
----------
obj_attr : obj_attr_type
obj_attr_description
"""
class_attr = 'something'
def __init__(self, arg='something else'):
self.obj_attr = arg
EDIT: Just wanted to note that I'm switching to Napoleon, which says it supports attributes, but not specifically class or instance attributes.
I tried what is mentioned in the How to Document file provided in numpy. It mentions the documentation of class attributes should be handled as follows.
An Attributes section, located below the Parameters section, may be used to describe class variables:
Attributes ---------- x : float The X coordinate. y : float The Y coordinate.
It goes on to mention that instance properties should have their own documentation and only be listed by name.
That makes sense but I can't find any examples of this in the numpy source code. The closest I found did something different in ABCPolyBase class.
Attributes
----------
coef : (N,) ndarray
...
Class Attributes
----------------
maxpower : int
In my opinion, the documentation used in the _polybase.py
class is legible but I do not believe the Class Attributes
usage will work with Sphinx autodoc summaries.
I hope this information is helpful.