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 пытается разбивать их на страницы для удобства чтения. Если задана переменная среды MANPAGER или PAGER, pydoc использует её значение в качестве программы для постраничного вывода. Если заданы обе переменные, используется MANPAGER.

Если перед аргументом указать флаг -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-адрес или локальный каталог со страницами справочника по библиотеке.