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

python -m 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. python -m 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.

python -m pydoc -n <hostname> will start the server listening at the given hostname. By default the hostname is 'localhost' but if you want the server to be reached from other machines, you may want to change the host name that the server responds to. During development this is especially useful if you want to run pydoc from within a container.

python -m pydoc -b will start the server and additionally open a web browser to a module index page. Each served page has a navigation bar at the top where you can Get help on an individual item, Search all modules with a keyword in their synopsis line, and go to the Module index, Topics and Keywords 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.

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.