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

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

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

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

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

pydoc sys

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

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

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

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

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

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

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

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

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