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