pydoc — Генератор документации и система интерактивной помощи¶
Источник: Lib/pydoc.py
Модуль pydoc автоматически генерирует документацию по модулям Python. Документация может быть представлена в виде страниц текста на консоли, передана в веб-браузер или сохранена в HTML-файлах.
Для модулей, классов, функций и методов отображаемая документация берется из docstring (т.е. атрибута __doc__) объекта и рекурсивно из его документируемых членов. Если docstring отсутствует, pydoc пытается получить описание из блока строк комментариев непосредственно над определением класса, функции или метода в исходном файле или в верхней части модуля (см. inspect.getcomments()).
Встроенная функция help() вызывает систему интерактивной справки в интерактивном интерпретаторе, который использует pydoc для генерации документации в виде текста на консоли. Эту же текстовую документацию можно просмотреть и вне интерпретатора Python, запустив pydoc как скрипт в командной строке операционной системы. Например, выполнив
python -m pydoc sys
в приглашении оболочки выведет документацию по модулю sys в стиле, похожем на страницы руководства, показываемые командой Unix man. Аргументом команды pydoc может быть имя функции, модуля или пакета или точечная ссылка на класс, метод или функцию в модуле или модуле в пакете. Если аргумент pydoc выглядит как путь (то есть содержит разделитель путей для вашей операционной системы, например, косую черту в Unix) и ссылается на существующий файл с исходным кодом Python, то документация будет создана для этого файла.
Примечание
Чтобы найти объекты и документацию к ним, pydoc импортирует модуль(ы), который(ые) нужно документировать. Таким образом, любой код на уровне модуля будет выполнен в этом случае. Используйте защиту if __name__ == '__main__':, чтобы выполнять код только тогда, когда файл вызывается как сценарий, а не просто импортируется.
При печати вывода на консоль 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 или на локальный каталог, содержащий страницы справочного руководства библиотеки.
Изменено в версии 3.2: Добавлена опция -b.
Изменено в версии 3.3: Опция командной строки -g была удалена.
Изменено в версии 3.4: pydoc теперь использует inspect.signature(), а не inspect.getfullargspec() для извлечения информации о подписи из вызываемых файлов.
Изменено в версии 3.7: Добавлена опция -n.