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 используется, когда нужен программный доступ к отформатированному тексту без запуска внешних программ.

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

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

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 предоставляет более интегрированное решение, извлекающее информацию непосредственно из объектов интерпретатора.

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

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

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)}')

питон pydoc.render_doc function comments

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