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

Nouveau dans la version 2.1.

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.

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting Web browsers. pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred Web browser. pydoc -g will start the server and additionally bring up a small Tkinter-based graphical interface to help you search for documentation pages.

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.

Module docs for core modules are assumed to reside in https://docs.python.org/library/. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.