pydoc — Генератор документации и система онлайн-справки

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

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

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

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

python -m pydoc sys

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

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

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

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

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

python -m pydoc -n <hostname> запустит сервер, прослушивающий указанный хост. По умолчанию хост — 'localhost', но если вы хотите, чтобы к серверу можно было подключиться с других компьютеров, вы можете изменить имя хоста, к которому отвечает сервер. Во время разработки это особенно полезно, если вы хотите запустить pydoc из контейнера.

python -m pydoc -b запустит сервер и дополнительно откроет веб-браузер для страницы индекса модулей. На каждой отображаемой странице есть навигационная панель в верхней части, где вы можете Получить справку по отдельному элементу, Найти все модули с ключевым словом в строке описания, перейти на страницы Индекс модулей, Разделы и Ключевые слова.

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

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