13

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Nick Sweet
  • 2,030
  • 3
  • 31
  • 48
  • 3
    The difference between "class" and "object" attributes in python are pretty subtle so I think the difference is glossed over in the standards. Take a look [here](http://www.toptal.com/python/python-class-attributes-an-overly-thorough-guide) for a discussion of how class and instance attributes don't behave as many would expect them to in python. – Bi Rico Feb 13 '15 at 00:11

1 Answers1

13

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.

erik-e
  • 3,721
  • 1
  • 21
  • 19
  • Good digging - thanks! I was wondering why instance attributes should be left undocumented – I find those a lot more useful than the class attributes (especially since, as @Bi Rico showed, instance attributes supercede class attributes). – Nick Sweet Feb 16 '15 at 18:36
  • I'm wondering if I'm going to have to extend Napoleon to be able to use Class or Instance Attributes - it doesn't look like they list those separately in their documentation: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html – Nick Sweet Feb 19 '15 at 19:40
  • There is an opened issue on Sphinx about the confusion documenting class and instance attributes: https://github.com/sphinx-doc/sphinx/issues/3141 – x0s May 09 '17 at 11:51