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

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

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

Для модулей, классов, функций и методов показываемая документация берётся из docstring (то есть из атрибута __doc__) объекта, а также рекурсивно из его документируемых членов. Если docstring отсутствует, 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/ в вашем любимом веб-браузере. Если указать 0 в качестве номера порта, будет выбран произвольный свободный порт.

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

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

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