Pydoc.render doc: примеры (PYTHON)

Генерация документации через pydoc.render_doc в Python
Раздел: Документация, Утилиты
pydoc.render_doc(obj: object, renderer: callable = ...): str
типовые примерыpydoc.render doc на php, c#, sql, javapydoc.render doc изменения pythonпримеры расширенные

Описание функции pydoc.render_doc

Функция pydoc.render_doc является частью стандартного модуля pydoc в Python. Она генерирует текстовую или HTML-документацию для любого объекта Python: модуля, класса, функции, метода или атрибута. Её применяют для программного получения справки в формате, аналогичном выводу встроенной функции help(), но с возможностью дальнейшей обработки или кастомизации.

Основное назначение - создание строкового представления документации, которое можно сохранить в файл, отправить по сети или вывести в пользовательский интерфейс.

Аргументы функции

  • object (обязательный): Объект Python, для которого требуется сгенерировать документацию. Может быть модулем, классом, функцией, методом, свойством или любым другим объектом.
  • renderer (опциональный, по умолчанию pydoc.plaintext): Функция-рендерер, определяющая формат вывода. Основные варианты:
    • pydoc.plaintext: Рендеринг в обычный текст (используется по умолчанию).
    • pydoc.html: Рендеринг в HTML-разметку.
    • pydoc.text: Альтернативный рендерер для текста.
  • title (опциональный, по умолчанию 'Python Library Documentation: %s'): Заголовок документации. В строке можно использовать спецификатор %s, который будет заменён на имя объекта.
  • forceload (опциональный, по умолчанию 0 или False): Если установлен в 1 или True, модуль будет принудительно перезагружен с помощью importlib.reload() перед генерацией документации. Полезно при работе с изменёнными модулями без перезапуска интерпретатора.

Возвращаемое значение

Функция возвращает строку (str), содержащую отформатированную документацию для переданного объекта в соответствии с выбранным рендерером. Если документация отсутствует, выводится информация о структуре объекта (например, список его методов и атрибутов).

Короткие примеры использования

Пример получения текстовой документации для встроенной функции len:

import pydoc
doc_text = pydoc.render_doc(len)
print(doc_text[:300])
Help on built-in function len in module builtins:

len(obj, /)
    Return the number of items in a container.

Пример генерации HTML-документации для модуля math:

import pydoc
html_doc = pydoc.render_doc('math', renderer=pydoc.html)
print(html_doc[:400])
<!DOCTYPE html>
<html>
<head>
    <title>Python Library Documentation: math</title>
</head>
<body>
<h1>Help on module math:</h1>

Пример с кастомным заголовком и принудительной загрузкой модуля:

import pydoc
import mymodule
doc = pydoc.render_doc(mymodule, title='Документация: %s', forceload=1)
print(doc.split('\n')[0])
Документация: mymodule

Похожие функции в Python

  • help(object): Встроенная функция, интерактивно выводящая документацию в консоль. Использует pydoc internally. pydoc.render_doc предпочтительнее, когда требуется получить документацию в виде строки для программной обработки, а не для немедленного вывода.
  • object.__doc__: Строковый атрибут, содержащий raw docstring объекта. pydoc.render_doc предоставляет более полную и отформатированную информацию, включая наследование, сигнатуры методов и список атрибутов.
  • inspect.getdoc(object): Функция из модуля inspect, возвращающая очищенный docstring. Она менее ресурсоёмкая, но даёт только сырой текст документации без дополнительной структуры.
  • pydoc.doc(object): Открывает документацию в веб-браузере или текстовом pager. pydoc.render_doc используется, когда нужен программный доступ к отформатированному тексту без запуска внешних программ.

Типичные ошибки при использовании

Ошибка при передаче несуществующего имени модуля в виде строки:

import pydoc
doc = pydoc.render_doc('non_existent_module')
print(doc)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
ImportError: No module named 'non_existent_module'

Попытка использовать рендерер, который не является вызываемым объектом:

import pydoc
doc = pydoc.render_doc(len, renderer='html')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
TypeError: 'str' object is not callable

Ошибка при указании неверного порядка аргументов (в старых версиях Python порядок renderer и forceload мог отличаться):

import pydoc
# В Python 3.7 renderer был после forceload
doc = pydoc.render_doc(len, pydoc.html, forceload=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
TypeError: render_doc() takes at most 3 arguments (4 given)

Чтобы избежать этой проблемы, рекомендуется использовать именованные аргументы.

Изменения в последних версиях Python

В Python 3.10 были внесены изменения в модуль pydoc, улучшающие обработку аннотаций и производительность. Однако сигнатура pydoc.render_doc осталась стабильной.

В Python 3.11 оптимизирована работа с большими модулями, что может повлиять на скорость генерации документации.

Важное изменение произошло в Python 3.7: параметры renderer и forceload стали keyword-only в некоторых контекстах, что повысило ясность кода. Рекомендуется всегда использовать именованные аргументы для этих параметров.

Расширенные примеры использования

Пример сохранения HTML-документации модуля в файл:

Пример python
import pydoc
html_content = pydoc.render_doc('csv', renderer=pydoc.html)
with open('csv_documentation.html', 'w', encoding='utf-8') as f:
    f.write(html_content)
print('Документация сохранена в csv_documentation.html')

Пример создания простой веб-системы документации для списка модулей:

Пример python
import pydoc
modules = ['os', 'sys', 'json']
for module_name in modules:
    doc = pydoc.render_doc(module_name, renderer=pydoc.html)
    filename = f'{module_name}_doc.html'
    with open(filename, 'w', encoding='utf-8') as f:
        f.write(doc)
    print(f'Создан файл {filename}')

Пример использования кастомного рендерера для вывода документации в упрощённом текстовом формате:

Пример python
import pydoc
def custom_render(doc, title):
    # Упрощённый рендерер: только заголовок и первая строка docstring
    lines = doc.split('\n')
    simplified = f'Тема: {title}\nКратко: {lines[0] if lines else "Нет описания"}'
    return simplified
# Получаем сырые данные документации
raw_doc = pydoc.render_doc(str, renderer=pydoc.plaintext)
# Применяем кастомный рендерер
custom_doc = custom_render(raw_doc, 'Класс str')
print(custom_doc)
Тема: Класс str
Кратко: Help on class str in module builtins:

Пример программного извлечения только сигнатур методов из документации класса:

Пример python
import pydoc
import re
doc_text = pydoc.render_doc(dict)
# Ищем строки, содержащие сигнатуры методов (например, метод(...))
signatures = re.findall(r'^\s*\w+\([^)]*\)', doc_text, re.MULTILINE)
print('Некоторые методы dict:')
for sig in signatures[:5]:
    print(f'  {sig}')
Некоторые методы dict:
  clear()
  copy()
  fromkeys(iterable[, value])
  get(key[, default])
  items()

Пример сравнения документации двух версий одного модуля с принудительной перезагрузкой:

Пример python
import pydoc
import mymodule
# Первоначальная документация
doc1 = pydoc.render_doc(mymodule)
# Внесены изменения в модуль mymodule...
# Получаем обновлённую документацию с forceload
doc2 = pydoc.render_doc(mymodule, forceload=1)
# Сравниваем (примитивно по длине)
print(f'Длина документации до: {len(doc1)}')
print(f'Длина документации после: {len(doc2)}')

Аналоги функции в других языках программирования

Концепция программного доступа к документации существует во многих языках, но реализация и возможности различаются.

JavaScript (JSDoc)

// Документация генерируется инструментами типа JSDoc из комментариев.
// Пример комментария:
/**
 * Возвращает сумму двух чисел.
 * @param {number} a Первое число.
 * @param {number} b Второе число.
 * @returns {number} Сумма a и b.
 */
function sum(a, b) {
    return a + b;
}
// Для получения документации в runtime используются специализированные библиотеки.

Java (Javadoc)

// Документация извлекается из исходного кода утилитой javadoc.
// Пример комментария:
/**
 * Возвращает сумму двух чисел.
 * @param a первое число
 * @param b второе число
 * @return сумма a и b
 */
public int sum(int a, int b) {
    return a + b;
}
// В runtime доступ к документации ограничен, требуется использование reflection и анализ исходных файлов.

PHP (phpDocumentor)

// Документация генерируется из DocBlock комментариев.
/**
 * Возвращает сумму двух чисел.
 *
 * @param int $a Первое число.
 * @param int $b Второе число.
 *
 * @return int Сумма $a и $b.
 */
function sum($a, $b) {
    return $a + $b;
}
// Reflection API позволяет получить DocBlock в runtime.
$reflection = new ReflectionFunction('sum');
echo $reflection->getDocComment();

Golang (godoc)

// Документация извлекается из комментариев и объявлений.
// Комментарий должен находиться непосредственно перед элементом.
// sum возвращает сумму двух целых чисел.
func sum(a int, b int) int {
    return a + b
}
// godoc -http=:6060 запускает веб-сервер с документацией.
// Программный доступ через go/doc и go/ast пакеты.

Отличия от Python

В отличие от Python, где pydoc.render_doc работает в runtime и не требует дополнительных инструментов, во многих языках документация генерируется на этапе сборки из комментариев. Python предоставляет более интегрированное решение, извлекающее информацию непосредственно из объектов интерпретатора.

питон pydoc.render_doc function comments

En
Pydoc.render doc Render an object's documentation as HTML