26.2. 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/ в любом веб-браузере. Указание 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 или локальному каталогу, содержащему страницы Справочного руководства по библиотеке.