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

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

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

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