Docstrings

La nomenclature et le caneva pour les docstrings est présenté. Le langage markup reStructedText est employé pour faciliter la génération des pages HTML avec l'outil Sphinx.

reStructuredText

La documentation concernant reST. Ceci est une lecture facultative la plupart des markup ne sont pas utile.

Sphinx

Sphinx est l'outil utilisé par la bibliothèque standard de python pour générer leur documentation. Il met l'emphase sur générer des documents explicatif. Cependant, il permet aussi de générer la documentation d'API, ce qui est l'élément recherché.

Caneva

Exemple d'une docstring pour une fonction quelconque. Les types sont facultatifs, ne les ajouter que s'ils ne sont pas évident.

def send_message(sender, priority)
"""Description courte (en moins de 80 caractères)...

   :param str sender: La personne qui envoi le message
   :param priority: La priorité du message: 1 à 5
   :type priority: integer or None
   :return: L'id du message
   :rtype: int
   :raises ValueError: Si le message excède 160 caractères
"""