pydoc — Генератор документации и онлайн-справочная система.¶
Kod źródłowy: Lib/pydoc.py
Модуль pydoc автоматически генерирует документацию из модулей Python. Документация может быть представлена в виде страниц текста на консоли, отображена в веб-браузере или сохранена в файлах HTML.
Для модулей, классов, функций и методов отображаемая документация получается из строки документации (т.е. атрибута __doc__) объекта и рекурсивно из его документируемых членов. Если строка документации отсутствует, pydoc пытается получить описание из блока строк комментариев чуть выше определения класса, функции или метода в исходном файле или в верхней части модуля (см.: func:inspect.getcomments).
Встроенная функция help() вызывает интерактивную справочную систему в интерактивном интерпретаторе, который использует pydoc для генерации документации в виде текста на консоли. Эту же текстовую документацию можно просмотреть и вне интерпретатора Python, запустив pydoc как скрипт в командной строке операционной системы. Например, запуск
python -m pydoc sys
у підказці оболонки відобразить документацію щодо модуля sys у стилі, подібному до сторінок посібника, показаних командою Unix man. Аргументом pydoc може бути назва функції, модуля чи пакета, або посилання з крапками на клас, метод або функцію в межах модуля чи модуля в пакеті. Якщо аргумент pydoc виглядає як шлях (тобто він містить роздільник шляхів для вашої операційної системи, наприклад косу риску в Unix), і посилається на існуючий вихідний файл Python, тоді створюється документація для цей файл.
Informacja
Чтобы найти объекты и их документацию, pydoc импортирует модули, подлежащие документированию. Следовательно, в этом случае будет выполнен любой код на уровне модуля. Используйте защиту if __name__ == '__main__':, чтобы выполнять код только тогда, когда файл вызывается как скрипт, а не просто импортируется.
При выводе вывода на консоль 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 <имя_хоста> запустит сервер, прослушивающий указанное имя хоста. По умолчанию имя хоста — «localhost», но если вы хотите, чтобы сервер был доступен с других компьютеров, вы можете изменить имя хоста, на которое отвечает сервер. Во время разработки это особенно полезно, если вы хотите запустить pydoc из контейнера.
python -m pydoc -b запустит сервер и дополнительно откроет в веб-браузере индексную страницу модуля. Каждая обслуживаемая страница имеет панель навигации вверху, где вы можете Получить справку по отдельному элементу, Искать все модули по ключевому слову в строке синопсиса и перейти к Индексу модулей, Темам и *Ключевым словам. * страницы.
Коли pydoc створює документацію, вона використовує поточне середовище та шлях для пошуку модулів. Таким чином, виклик pydoc spam документує саме ту версію модуля, яку ви отримаєте, якщо запустите інтерпретатор Python і введете import spam.
Предполагается, что документация по основным модулям находится в https://docs.python.org/XY/library/, где X и Y — это основной и дополнительный номера версий Python. устный переводчик. Это можно переопределить, установив для переменной среды PYTHONDOCS другой URL-адрес или локальный каталог, содержащий страницы справочного руководства по библиотеке.
Zmienione w wersji 3.2: Додано опцію -b.
Zmienione w wersji 3.3: Параметр командного рядка -g видалено.
Zmienione w wersji 3.4: pydoc теперь использует inspect.signature() вместо inspect.getfullargspec() для извлечения информации о подписи из вызываемых объектов.
Zmienione w wersji 3.7: Додано опцію -n.