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 перед аргументом заставит pydoc записать 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() для извлечения информации о сигнатуре из вызываемых объектов.