Menu
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.
431
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.
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.
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.
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.
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.
119
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
