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