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 пытается разбить вывод на страницы, чтобы его было удобнее читать. Если задана переменная среды MANPAGER или PAGER, pydoc использует её значение как программу для постраничного вывода. Если заданы обе переменные, используется MANPAGER.

Если перед аргументом указать флаг -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 запустит сервер и дополнительно откроет в браузере страницу с индексом модулей. В верхней части каждой страницы есть панель навигации, с помощью которой можно получить справку (Get) по отдельному элементу, выполнить поиск (Search) по всем модулям по ключевому слову из строки краткого описания, а также перейти на страницы индекса модулей, тем и ключевых слов.

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

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