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

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

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

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