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

Code source : Lib/pydoc.py


The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.

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 native 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. Specifying 0 as the port number will select an arbitrary unused port.

pydoc -n <hostname> démarre le serveur en écoutant sur le port donné en argument. Par défaut le nom d’hôte est localhost mais si vous voulez que le serveur soit joignable par d’autres machines, vous avez la possibilité de changer le nom de l’hôte auquel le serveur répond. Dans le développement, c’est particulièrement utile si vous souhaitez exécuter pydoc depuis un conteneur.

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.

Modifié dans la version 3.7: Ajout de l’option -n.