25.1. pydoc – генератор документации и справочная система¶pydoc – Documentation generator and online help system
Модуль pydoc автоматически создаёт документацию из модулей Python. Документация может быть отображена в виде текстовых страниц на консоли, передана веб-браузеру или сохранена в HTML-файлы.
Встроенная функция help() вызывает справочную систему в интерактивном интерпретаторе, которая использует pydoc для создания своей документации в виде текста на консоли. Эту же текстовую документацию можно просмотреть и за пределами интерпретатора Python, запустив pydoc как скрипт из командной строки операционной системы. Например, выполнение
pydoc sys
в командной строке отобразит документацию по модулю sys в стиле, напоминающем страницы руководства Unix-команды man. Аргументом pydoc может быть имя функции, модуля или пакета, а также точечная ссылка на класс, метод или функцию внутри модуля или пакета. Если аргумент pydoc выглядит как путь (то есть содержит разделитель пути для вашей операционной системы, например, косую черту в Unix) и указывает на существующий файл исходного кода Python, то документация создаётся для этого файла.
Примечание
Чтобы найти объекты и их документацию, pydoc импортирует документируемый модуль (модули). Поэтому любой код на уровне модуля будет выполнен в этот момент. Используйте защиту if __name__ == '__main__':, чтобы код выполнялся только при запуске файла как скрипта, а не при импорте.
Указание флага -w перед аргументом приведёт к записи HTML-документации в файл в текущем каталоге вместо вывода текста на консоль.
Указание флага -k перед аргументом выполняет поиск по строкам-синопсисам всех доступных модулей для ключевого слова, заданного в качестве аргумента, снова в стиле, похожем на команду Unix man. Строка-синопсис модуля – это первая строка его строки документации.
Вы также можете использовать pydoc для запуска HTTP-сервера на локальной машине, который будет предоставлять документацию посещающим веб-браузерам. pydoc -p 1234 запустит HTTP-сервер на порту 1234, позволяя просматривать документацию по адресу http://localhost:1234/ в вашем любимом веб-браузере. pydoc -g запустит сервер и дополнительно откроет небольшой графический интерфейс на основе tkinter для поиска страниц документации.
Когда pydoc создаёт документацию, он использует текущее окружение и путь для поиска модулей. Таким образом, вызов pydoc spam документирует именно ту версию модуля, которую вы получили бы, запустив интерпретатор Python и введя import spam.
Документация для основных модулей, как предполагается, находится по адресу http://docs.python.org/X.Y/library/, где X и Y – это номера старшей и младшей версии интерпретатора Python. Это поведение можно переопределить, задав переменную окружения PYTHONDOCS с другим URL или локальным каталогом, содержащим страницы справочного руководства по библиотеке.