# 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.