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 импортирует модули, подлежащие
документированию. Поэтому в этом случае будет выполняться любой код на
уровне модуля. Используйте защиту if __name__ == '__main__':, чтобы выполнить только
код, когда файл будет рассматриваться как сценарий и не просто импортирован.
При печати выходных данных на консоль 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 запустит сервер и дополнительно откроет веб-браузер на индексную страницу модуля. Каждая поданная страница имеет панель навигации в верхней части, где можно получить помощь по отдельному элементу, найти все модули с ключевой в их строке обзора и перейти на страницы Module index, Topics и Keywords.
Когда pydoc производит документацию, он использует текущую окружающую
среду и путь, чтобы определить местонахождение модулей. Таким образом, вызов
pydoc spam документирует именно ту версию модуля, которую вы получили бы, если
бы запустили Python интерпретатор и набрали import spam.
Модуль docs для основных модулей, как предполагается, находятся в
https://docs.python.org/X.Y/library/, где X и Y - мажорные и минорные номера
версий Python интерпретатора. Это можно переопределить, установив для
переменной среды PYTHONDOCS другой URL-адрес или каталог локальная,
содержащий страницы справочного руководства библиотеки.
Изменено в версии 3.2: Добавлен параметр -b.
Изменено в версии 3.3: Параметр командной строки -g был удален.
Изменено в версии 3.4: Теперь pydoc использует inspect.signature(), а не inspect.getfullargspec() для извлечения
сигнатуры информации из вызываемых объектах.
Изменено в версии 3.7: Добавлен параметр -n.