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

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

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

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

pydoc sys

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

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

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

Можно также использовать pydoc для запуска HTTP-сервера на локальной машине, который будет выдавать документацию посещающим веб-браузерам. Команда pydoc -p 1234 запустит HTTP-сервер на порту 1234, позволяя просматривать документацию по адресу http://localhost:1234/ в вашем любимом веб-браузере. Если указать 0 в качестве номера порта, будет выбран произвольный свободный порт.

pydoc -g запускает сервер и дополнительно открывает небольшой tkinter-графический интерфейс для поиска страниц документации. Опция -g устарела, так как теперь сервером можно управлять напрямую из HTTP-клиентов.

pydoc -b запустит сервер и дополнительно откроет веб- браузер на странице индекса модулей. На каждой обслуживаемой странице вверху есть панель навигации, где можно получить справку по отдельному элементу, выполнить поиск по всем модулям с ключевым словом в строке аннотации, а также перейти на страницы Module index, Topics и Keywords.

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

Модульная документация для основных модулей считается расположенной по адресу http://docs.python.org/X.Y/library/, где X и Y – это номера основной и дополнительной версии интерпретатора Python. Это можно переопределить, задав переменную окружения PYTHONDOCS, указав другой URL или локальный каталог, содержащий страницы справочника библиотеки.