pydoc – Генератор документации и справочная система¶pydoc – Documentation generator and online help system

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