pydoc — Генератор документации и интерактивная справочная система

Модуль 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 -n <hostname> запустит сервер, прослушивающий данное имя хоста. По умолчанию имя хоста — «localhost», но если вы хотите, чтобы сервер был доступен с других компьютеров, вы можете изменить имя хоста, на которое отвечает сервер. Во время разработки это особенно полезно, если вы хотите запустить pydoc из контейнера.

pydoc -b запустит сервер и дополнительно откроет в веб-браузере индексную страницу модуля. У каждой обслуживаемой страницы есть панель навигации вверху. Данная панель содержит следующие элементы: Get — предоставляет помощь по отдельному элементу, Search — ищет модули по ключевому слову в строке краткого описания, а также предоставляет переход на страницы Module index, Topics и Keywords.

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

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