Comment documenter une constante de module en Python?
j'ai un module, errors.py dans lequel plusieurs constantes globales sont définies (note: je comprends que Python n'a pas de constantes, mais je les ai définies par convention en utilisant UPPERCASE).
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
en utilisant reStructuredText Comment puis-je documenter ces constantes? Comme vous pouvez le voir j'ai listé un docstring au-dessus d'eux, mais je n'ai pas trouvé de documentation qui indique de faire cela, je l'ai juste fait comme une supposition.
5 réponses
malheureusement, les variables (et les constantes) n'ont pas de docstrings. Après tout, la variable est juste un nom pour un entier, et vous ne voudriez pas attacher un docstring au nombre 1 de la façon dont vous le feriez à une fonction ou à un objet de classe.
si vous regardez presque n'importe quel module dans le stdlib, comme pickle , vous verrez que la seule documentation qu'ils utilisent est des commentaires. Et oui, cela signifie que help(pickle) montre seulement ceci:
DATA
APPEND = b'a'
APPENDS = b'e'
…
... ignorant complètement les commentaires. Si vous voulez que vos docs apparaissent dans l'aide intégrée, vous devez les ajouter à docstring du module, ce qui n'est pas exactement idéal.
mais Sphinx peut faire plus que L'aide intégrée peut. Vous pouvez le configurer pour extraire les commentaires sur les constantes, ou utiliser autodata pour le faire semi-automatiquement. Par exemple:
#: Indicates some unknown error.
API_ERROR = 1
lignes multiples #: avant toute déclaration d'affectation, ou un seul #: commentaire à la droite de la déclaration, fonctionnent effectivement de la même façon que les docstrings sur les objets ramassés par autodoc. Ce qui inclut la gestion de inline rST, et l'auto-génération d'un en-tête rST pour le nom de la variable; il n'y a rien de plus que vous devez faire pour que cela fonctionne.
comme note latérale, vous pouvez envisager d'utiliser un enum au lieu de constantes séparées comme celle-ci. Si vous n'utilisez pas Python 3.4 (ce que vous n'êtes probablement pas encore...), il y a un paquet backport.enum pour 3.2+, ou flufl.enum (qui n'est pas identique, mais il est similaire, car il a été la principale source d'inspiration pour le module stdlib) pour 2.6+.
les instances Enum (pas flufl.enum , mais la version stdlib/backport) peuvent même avoir des docstrings:
class MyErrors(enum.Enum):
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
bien qu'ils ne se présentent malheureusement pas dans help(MyErrors.MISSING_PARAMS) , ce sont des cordons que Sphinx autodoc peut détecter.
vous pouvez utiliser le hash + deux points pour documenter les attributs (niveau de classe ou de module).
#: Use this content as input for moo to do bar
MY_CONSTANT = "foo"
Ce sera ramassé certains document de générateurs.
un exemple ici, ne pouvait pas trouver un meilleur Sphinx propriétés du module de document
si vous mettez une chaîne de caractères après la variable, alors sphinx la récupérera comme documentation de la variable. Je sais que ça marche parce que je le fais partout. Comme ceci:
FOO = 1
"""
Constant signifying foo.
Blah blah blah...
""" # pylint: disable=W0105
la directive pylint dit à pylint d'éviter de signaler la documentation comme étant une déclaration sans effet.
il s'agit d'une question plus ancienne, mais j'ai remarqué qu'il manquait une réponse pertinente.
ou vous pouvez simplement inclure une description des constantes dans le docstring du module via .. py:données:: . De cette façon, la documentation est également disponible via l'aide interactive. Sphinx le rendra bien.
"""
Docstring for my module.
.. data:: API_ERROR
Indicates some unknown error.
.. data:: BAD_REQUEST
Indicates that the request was bad in some way.
.. data:: MISSING_PARAMS
Indicates that the request is missing required parameters.
"""
je pense que vous n'avez pas de chance ici.
Python ne supporte pas directement les docstrings sur les variables: il n'y a aucun attribut qui peut être attaché aux variables et récupéré de manière interactive comme l'attribut
__doc__sur les modules, les classes et les fonctions.
Source .