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

Новая в версии 2.1.

Исходный код: 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/ в вашем браузере. pydoc -g запустит сервер и дополнительно откроет небольшой интерфейс на основе Tkinter, чтобы помочь вам найти страницы документации.

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

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