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 пытается выполнить постраничный вывод для удобства чтения. Если переменная среды 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 запустит сервер и дополнительно откроет веб-браузер для страницы индекса модулей. Каждая отображаемая страница имеет навигационную панель вверху, где вы можете Получить справку по отдельному элементу, Поиск всех модулей по ключевому слову в их строке описания и перейти на страницы Индекс модулей, Разделы и Ключевые слова.

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

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