26.2. pydoc — Générateur de documentation et système d’aide en ligne

Code source : Lib/pydoc.py

Le module pydoc génère automatiquement de la documentation à partir de modules Python. La documentation peut se présenter sous forme de pages de texte dans la console, rendue dans un navigateur web, ou sauvegardée dans des fichiers HTML.

Pour les modules, classes, fonctions et méthodes, la documentation affichée est tirée de la docstring (c.à.d de l’attribut __doc__) de l’objet et ce, de manière récursive pour les membres qui peuvent être documentés. S’il n’y a pas de docstring, pydoc essaie d’obtenir une description à partir du bloc de commentaires juste au-dessus de la définition de la classe, fonction ou méthode du fichier source, ou en haut du module (voir inspect.getcomments()).

La fonction intégrée help() appelle le système d’aide en ligne dans l’interpréteur Python qui utilise pydoc pour générer sa documentation sous forme textuelle dans la console. Cette même documentation peut aussi être consultée à l’extérieur de l’interpréteur Python en lançant pydoc dans le terminal du système d’exploitation. Par exemple en lançant :

pydoc sys

dans un terminal, cela affiche la documentation du module sys dans un style similaire à la commande Unix man. On peut passer comme argument à pydoc le nom d’une fonction, d’un module, d’un paquet, ou une référence pointant vers une classe, une méthode, ou une fonction dans un module ou dans un paquet. Si l’argument passé à pydoc est un chemin (c.à.d qu’il contient des séparateurs de chemin tels que la barre oblique / dans Unix), et fait référence à un fichier source Python existant, alors la documentation est générée pour ce fichier.

Note

Afin de trouver des objets et leur documentation, pydoc importe le ou les modules à documenter. Par conséquent tout code au niveau du module sera exécuté à cette occasion. Utiliser if __name__ == ‘__main__’: évite d’exécuter du code lorsqu’un fichier est appelé directement et non pas importé.

Lorsque l’on affiche une sortie sur la console, pydoc essaye de créer une pagination pour faciliter la lecture. Si la variable d’environnement PAGER est configurée, pydoc utilise sa valeur comme programme de pagination.

Ajouter une option -w avant l’argument entraine l’enregistrement de la documentation HTML générée dans un fichier du répertoire courant au lieu de l’afficher dans la console.

Ajouter une option -w avant l’argument cherche les lignes de résumé de tous les modules disponibles pour le mot clé donné comme argument, ceci à la manière de la commande Unix man. Les lignes de résumé d’un module sont les premières lignes de sa docstring.

Vous pouvez aussi utiliser pydoc pour lancer un serveur HTTP sur votre machine locale qui rendra la documentation consultable sur votre navigateur Web. pydoc -p 1234 lancera un serveur HTTP sur le port 1234, permettant de consulter la documentation à l’adresse http://localhost:1234/ dans votre navigateur web préféré. En précisant 0 comme numéro de port, un port non utilisé sera aléatoirement alloué.

pydoc -b démarre le serveur et ouvrira en plus un navigateur web vers une page d’index de module. Chaque page affichée a une barre de navigation en haut où vous pouvez Obtenir de l’aide sur un élément individuel, Rechercher tous les modules avec un mot-clé dans leur ligne de résumé, et aller dans les pages Index des modules, Thèmes et Mots clés.

Quand pydoc génère de la documentation, il utilise l’environnement et le chemin courant pour localiser les modules. Ainsi, en invoquant les documents pydoc spam en précisant la version du module, vous obtenez le même résultat qu’en lançant l’interpréteur Python et en tapant la commande import spam.

La documentation des modules principaux est supposée être hébergée sur https://docs.python.org/X.Y/library/ et https://docs.python.org/fr/X.Y/library pour la version française, où X et Y sont les versions respectivement majeures et mineures de l’interpréteur Python. Ces valeurs peuvent être redéfinies en configurant la variable d’environnement PYTHONDOCS sur une URL différente ou un répertoire local contenant les pages du manuel de la bibliothèque de référence.

Modifié dans la version 3.2: Ajout de l’option -b.

Modifié dans la version 3.3: Suppression de l’option -g.

Modifié dans la version 3.4: pydoc utilise à présent inspect.signature() plutôt que inspect.getfullargspec() pour extraire les informations de signatures des callables.