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

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

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