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

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

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

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

Встроенная функция help() вызывает интерактивную справочную систему interactive interpreter, которая использует 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-адрес или локальный каталог, содержащий страницы справочного руководства по библиотеке.