web-dev-qa-db-fra.com

Comment documenter les champs et les propriétés en Python?

Il est facile de documenter une classe ou une méthode 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 {}

Mais comment documenter un champ ou une propriété pour une utilisation dans les documents API ou help?

pythondocumentation
56
deamon

Python a un PEP ( 257 ) qui définit les conventions de Docstring. Concernant la documentation des attributs, il indique:

Littéraux de chaîne se produisant immédiatement après une simple affectation au niveau supérieur d'un module, d'une classe ou de __init__ la méthode est appelée "attribut docstrings".

Les éléments suivants sont donc considérés comme des attributs documentés:

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: Correction de la deuxième docstring)

60
Eli Bendersky

La documentation d'une propriété dans l'interpréteur python utilisant l'aide fonctionne bien pour moi, voir documentation de propriété . Remarque: l'opérateur d'aide magique d'IPython, ?, n'a pas affiché la propriété 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

Dans Sphinx, vous devez utiliser le :members: directive pour documenter les propriétés, voir documentation autodoc . Fonctionne comme un charme pour moi!

Les attributs seront également documentés par Sphinx si :members: est utilisé. Les docstrings pour les attributs peuvent être donnés sous forme de commentaires précédant l'attribut, mais en utilisant deux points suivant la marque de hachage, EG #: the foo attribute. Dans la documentation de l'autodoc Sphinx:

Pour les membres de données de module et les attributs de classe, la documentation peut être placée dans un commentaire avec une mise en forme spéciale (en utilisant un #: pour démarrer le commentaire au lieu de simplement #), ou dans une docstring après la définition. Les commentaires doivent être soit sur une ligne à part avant la définition, soit immédiatement après l'affectation sur la même ligne. Ce dernier formulaire est limité à une seule ligne.

9
Mark Mikofski

Documentez les attributs librement accessibles dans la classe docstring ou transformez-les en propriétés. Vous documentez correctement les propriétés, le problème pourrait être dans les classes 2.x et anciennes, qui ne prennent pas en charge les descripteurs - héritez de object dans ce cas.

3
Cat Plus Plus

Avec Sphinx notation/ Restructured Text dans vos docstrings, vous pouvez générer une documentation bien formatée à partir de vous Python sources automatiquement. Il prend également en charge les arguments et renvoie valeurs pour les fonctions - pas de champs pour autant que je sache, mais vous pouvez facilement créer une liste pour eux.

2
Sebastian Blask