如何用 Python 记录字段和属性？

用 Python 编写类或方法的文档很容易:

class Something:
""" Description of the class. """


def do_it(self):
""" Description of the method. """
pass


class_variable = 1 # How to comment?


@property
def give_me_some_special_dict(self):
""" doesn't work! Doc of general dict will be shown. """
return {}

但是如何为 API 文档或 help中使用的字段或属性编写文档呢？

29430 次浏览
小开

Document freely accessible attributes in the class docstring or make them into properties. You're documenting properties properly, the problem might be in 2.x and old-style classes, which don't support descriptors — inherit from object in that case.

小开

With Sphinx notation / Restructured Text in your docstrings you can generate nicely formatted documentation from you Python sources automatically. It also supports arguments and return values for functions - no fields as far as I know, but you can easily create a list for them.

小开
最佳答案

Python has a PEP (257) that defines Docstring Conventions. Regarding documentation of attributes, it states:

String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".

So the following are considered documented attributes:

class Foo(object):
velocity = 1
"""Foo's initial velocity - class variable"""


def __init__(self, args):
self.location = 0.0
"""Foo's initial location - instance variable"""

(Edit: Fixed second docstring)

小开

Documentation of a property in the python interpreter using help works fine for me, see proprerty documentation. Note: IPython's magic help operator, ?, did not display the property docstring.

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:


bar property

In Sphinx you must use the :members: directive to document properties, see autodoc documentation. Works like a charm for me!

Attributes will also be documented by Sphinx if :members: is used. Docstrings for attributes can be given as comments preceding the attribute, but using a colon following the hash mark, EG #: the foo attribute. From the Sphinx autodoc documentation:

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.


提交答案