PyConFr 2014

Lyon, October 25-28

PyConFR 2014

samedi 16:00:00–16:30:00

Les docstrings pour bien documenter son projet.

Adel Daouzli

Audience level:
Novice

Description

En Python, les fonctions, méthodes et classes peuvent être documentées en utilisant des docstrings. Python peut ainsi générer par introspection une documentation interne. Également des outils tel que Sphinx peuvent générer une documentation dans divers formats (HTML, PDF,..). Cependant il existe différents formats (reST, Epydoc, Google,..), alors que choisir, et comment changer de format (Pyment)?

Abstract

En Python, les fonctions, méthodes et classes peuvent être documentées en utilisant des docstrings.

Python peut ainsi générer par introspection une documentation interne dynamique. Les docstrings peuvent alors être accédées via l'attribut magique __doc__ ou via la fonction help() de l'interpréteur.

Par ailleurs, des outils tel que Sphinx peuvent générer une documentation externe dans divers formats de sortie (LaTeX, HTML, PDF,..).

Cependant il existe différents formats de docstrings (reStructuredText, Epytext, Google, Numpydoc,...).

Dans cette présentation nous allons passer en revue les principaux formats de docstrings avec leurs syntaxes. Nous verrons également les outils permettant de générer une documentation externe. Enfin nous nous arrêterons sur Pyment un outils permettant de générer automatiquement des squelettes de docstrings dans un format donné sur un fichier ou un module Python. Il permet aussi de convertir d'un format vers l'autre.

Voir le support de présentation

Sponsors