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

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

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

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

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

pydoc sys

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

Примечание

Для поиска объектов и их документации pydoc импортирует модуль(и), подлежащие документированию. Поэтому любой код на уровне модуля будет выполнен в этот момент. Используйте конструкцию if __name__ == '__main__': для выполнения кода только при вызове файла как скрипта, а не при его импорте.

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

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

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

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

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

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

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

Изменено в версии 3.2: Добавлен параметр -b.

Изменено в версии 3.3: Командная строка -g была удалена.

Изменено в версии 3.4: pydoc теперь использует inspect.signature() вместо inspect.getfullargspec() для извлечения информации о сигнатуре из вызываемых объектов.