Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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.

like image 431
Nick Sweet Avatar asked Feb 10 '15 17:02

Nick Sweet


People also ask

Which symbols are used to start and end a docstring?

The doc string line should begin with a capital letter and end with a period. The first line should be a short description. If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description.

Which is the correct location to place a docstring for a function?

Module docstrings are placed at the top of the file even before any imports. Module docstrings should include the following: A brief description of the module and its purpose. A list of any classes, exception, functions, and any other objects exported by the module.

What is Numpy style docstring?

numpydoc style docstrings are written in restructured text. They are composed of a short description of the object followed by a few required and optional sections. For functions and methods, these sections are: Required. Parameters.

How do you write a good docstring?

Best practicesAll modules, classes, methods, and functions, including the __init__ constructor in packages should have docstrings. Descriptions are capitalized and have end-of-sentence punctuation. Always use """Triple double quotes.""" around docstrings. Docstrings are not followed by a blank line.


1 Answers

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.

like image 119
erik-e Avatar answered Oct 19 '22 00:10

erik-e