Cómo documentar campos y propiedades en Python?

Question

Es fácil documentar una clase o método en 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 {} 

Pero cómo documentar un campo o propiedad para su uso en documentos de la API o help?

Answer 1

Python tiene un PEP (257) que define las Convenciones de Docstring. En cuanto a la documentación de los atributos, se indica: literales

Cuerda ocurre inmediatamente después de una tarea sencilla en el nivel superior de un módulo, clase o __init__ método son llamados "atributos" cadenas de documentación.

atributos documentados Así se consideran los siguientes:

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

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

(Edit: Fijo segunda cadena de documentación)

Answer 2

Documente los atributos de acceso libre en la clase docstring o conviértalos en propiedades. Está documentando las propiedades correctamente, el problema puede estar en clases 2.x y antiguas, que no son compatibles con los descriptores; heredan de object en ese caso.

Answer 3

Con notación Sphinx/Restructured Text en sus documentos, puede generar documentación muy formateada de sus fuentes de Python automáticamente. También admite argumentos y valores de retorno para funciones; no hay campos que yo sepa, pero puede crear fácilmente una lista para ellos.

Answer 4

Documentación de una propiedad en el intérprete Python usando ayuda funciona bien para mí, ver proprerty documentation. Nota: El operador de ayuda mágica de IPython, ?, hizo no muestra el docstring de la propiedad.

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

En Sphinx debe utilizar la directiva :members: para documentar propiedades, consulte autodoc documentation. ¡Funciona como un encanto para mí!

Los atributos también estarán documentados por Sphinx si se usa :members:. Las cadenas de documentos para los atributos se pueden dar como comentarios que preceden al atributo, pero usando dos puntos después de la marca de almohadilla, EG #: the foo attribute. De la documentación autodoc Sphinx:

Para los miembros de datos de los módulos y los atributos de clase, la documentación puede o bien ser puesto en un comentario con formato especial (usando un #: para iniciar el comentario en vez de sólo #), o en una cadena de documentación después de la definición. Los comentarios deben estar en una línea propia antes de la definición, o inmediatamente después de la asignación en la misma línea. La última forma está restringida a una sola línea.