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

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

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

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

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

python -m pydoc sys

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

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

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

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

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

python -m pydoc -n <hostname> запустит сервер, прослушивающий на указанном хосте. По умолчанию хост — 'localhost', но если вы хотите, чтобы к серверу можно было подключиться с других компьютеров, вы можете изменить имя хоста, к которому отвечает сервер. Это особенно полезно при разработке, если вы хотите запустить pydoc из контейнера.

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

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

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