5.5. Outils

5.5.1. Générateurs de documentation

5.5.1.1. Sphinx

Sphinx est un logiciel qui permet de créer très facilement de belles documentations pour les logiciels Python. Toutefois, sa puissance ne le limite pas à du code Python et il peut être utilisé pour rédiger d’autres documents [1]. De nombreux formats sont disponibles pour la sortie : PDF (via LaTeX), HTML…

Le langage de balisage ReST est utilisé par Sphinx afin de mettre en forme le contenu de la documentation. Il s’agit d’un langage très simple à apprendre et intuitif.

Warning

Sphinx ne supporte pas encore la version 3 de Python.

5.5.1.2. Autres

D’autres outils permettant de générer des documentations existent, mais ils sont généralement moins adaptés à Python et leur rendu est moins agréable. Voici une liste non exhaustive :

  • Doxygen : L’avantage de ce logiciel est de fonctionner avec la plupart des langages couramment utilisés (Python, PHP, C, Java…).
  • Epydoc : Logiciel utilisé historiquement pour les documentations Python.

5.5.2. Pylint

Pylint est un logiciel utilisable en ligne de commande qui permet d’analyser du code, dans le but de chercher des erreurs et de vérifier la bonne rédaction (respect de la PEP 8 — voir l’annexe Bonnes et mauvaises pratiques).

Il peut s’utiliser pour vérifier la syntaxe d’un fichier seul ou d’un package entier. Il s’utilise comme suit :

$ pylint package
$ pylint file.py

Un rapport détaillé des erreurs et des fautes de style (chacune identifiée par une catégorie) pour chaque fichier sera affiché. À la fin, le rapport indique un récapitulatif par modules et un autre global, en plus d’attribuer une note sur 10.

Pylint est très strict quant à la vérification du code, et il est souvent nécessaire de créer sa propre configuration afin qu’il accepte certaines formes qu’il considère comme des erreurs.

Footnotes

[1]D’ailleurs ce manuel a été rédigé grâce à Sphinx.

Table des matières

Sujet précédent

5.4. Éditeurs

Sujet suivant

5.6. Liens

Cette page