25.1. pydoc – генератор документации и интерактивная справочная система¶pydoc – Documentation generator and online help system

Исходный код: Lib/pydoc.py

Модуль pydoc автоматически создаёт документацию на основе модулей Python. Документация может выводиться в виде текстовых страниц на консоль, передаваться в веб-браузер или сохраняться в HTML-файлы.

Для модулей, классов, функций и методов отображаемая документация получена из докстринга (т.е. атрибута __doc__) объекта и рекурсивно из его документируемых членов. Если докстринг отсутствует, pydoc пытается получить описание из блока строк комментариев, расположенных непосредственно перед определением класса, функции или метода в исходном файле, или в начале модуля (см. inspect.getcomments()).

Встроенная функция help() вызывает справочную систему в интерактивном интерпретаторе, которая использует pydoc для генерации документации в виде текста на консоли. Этот же текстовый документ можно просматривать вне интерпретатора Python, запуская pydoc в качестве сценария в командной строке операционной системы. Например, выполнение

pydoc sys

в командной строке отобразит документацию по модулю sys в стиле, похожем на страницы руководства, выводимые командой Unix man. Аргументом для pydoc может быть имя функции, модуля или пакета, или точечная ссылка на класс, метод или функцию внутри модуля или модуля в пакете. Если аргумент для pydoc выглядит как путь (т.е. содержит разделитель пути вашей операционной системы, например, слеш в Unix) и указывает на существующий файл исходного кода Python, то документация генерируется для этого файла.

При выводе на консоль pydoc пытается разбить вывод на страницы для удобства чтения. Если установлена переменная окружения PAGER, pydoc будет использовать её значение в качестве программы разбиения на страницы.

Указание флага -w перед аргументом приведёт к записи HTML-документации в файл в текущем каталоге вместо отображения текста на консоли.

Указание флага -k перед аргументом приведёт к поиску строк синопсиса во всех доступных модулях для заданного ключевого слова, снова в стиле, похожем на команду Unix man. Строка синопсиса модуля – это первая строка его докстринга.

Вы также можете использовать pydoc для запуска HTTP-сервера на локальной машине, который будет обслуживать документацию для посещающих веб-браузеров. pydoc -p 1234 запустит HTTP-сервер на порту 1234, позволяя просматривать документацию по адресу http://localhost:1234/ в вашем любимом веб-браузере. pydoc -g запустит сервер и дополнительно откроет небольшой графический интерфейс на основе Tkinter для помощи в поиске страниц документации.

При генерации документации pydoc использует текущее окружение и путь для поиска модулей. Таким образом, вызов pydoc spam документирует именно ту версию модуля, которую вы получите, запустив интерпретатор Python и набрав import spam.

Документация модулей для основных модулей, как предполагается, находится по адресу https://docs.python.org/library/. Это можно переопределить, установив переменную окружения PYTHONDOCS на другой URL или на локальную директорию, содержащую страницы Справочного руководства по библиотеке.