pythonnumpyscipypython-sphinxsphinx-napoleon

How should I document class and object attributes using Numpy's style?


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.


Solution

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