Инструменты: help(), pydoc, Sphinx

Вы уже умеете писать docstring и type hints. Но кто их читает? Оказывается — не только люди! Python, IDE и специальные инструменты умеют превращать ваши docstring в красивую документацию. В этом уроке вы узнаете, какие инструменты для этого существуют и как ими пользоваться.

🗺️ Карта инструментов

Представьте: вы написали класс с хорошими docstring. Теперь у вас есть три уровня, на которых эта документация «оживает»:

Это не три разных подхода — это три уровня одного и того же. Начнём с самого простого.

🔍 help() — документация прямо в Python

REPL (Read-Eval-Print Loop) — это интерактивная оболочка Python. Вы запускаете python в терминале и попадаете туда: пишете код — Python сразу выполняет и показывает результат.

В REPL есть встроенная функция help(). Передайте ей любой объект — класс, функцию, модуль — и Python покажет всю документацию, которую вы написали в docstring.

Допустим, у нас есть такой класс:

class BankAccount:
    """Банковский счёт клиента.

    Хранит баланс и позволяет выполнять базовые операции:
    пополнение и снятие средств.

    Args:
        owner (str): Имя владельца счёта.
        balance (float): Начальный баланс. По умолчанию 0.
    """

    def __init__(self, owner: str, balance: float = 0) -> None:
        self.owner = owner
        self.balance = balance

    def deposit(self, amount: float) -> None:
        """Пополнить счёт на указанную сумму.

        Args:
            amount (float): Сумма пополнения. Должна быть положительной.
        """
        if amount <= 0:
            raise ValueError("Сумма должна быть положительной")
        self.balance += amount

    def withdraw(self, amount: float) -> float:
        """Снять деньги со счёта.

        Args:
            amount (float): Сумма снятия.

        Returns:
            float: Фактически снятая сумма.

        Raises:
            ValueError: Если сумма превышает баланс.
        """
        if amount > self.balance:
            raise ValueError("Недостаточно средств")
        self.balance -= amount
        return amount

Теперь запускаем Python, импортируем класс и вызываем help():

>>> from bank import BankAccount
>>> help(BankAccount)

Python выведет в терминал:

Help on class BankAccount in module bank:

class BankAccount(builtins.object)
 |  BankAccount(owner: str, balance: float = 0) -> None
 |
 |  Банковский счёт клиента.
 |
 |  Хранит баланс и позволяет выполнять базовые операции:
 |  пополнение и снятие средств.
 |
 |  Args:
 |      owner (str): Имя владельца счёта.
 |      balance (float): Начальный баланс. По умолчанию 0.
 |
 |  Methods defined here:
 |
 |  __init__(self, owner: str, balance: float = 0) -> None
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  deposit(self, amount: float) -> None
 |      Пополнить счёт на указанную сумму.
 |
 |      Args:
 |          amount (float): Сумма пополнения. Должна быть положительной.
 |
 |  withdraw(self, amount: float) -> float
 |      Снять деньги со счёта.
 |
 |      Args:
 |          amount (float): Сумма снятия.
 |
 |      Returns:
 |          float: Фактически снятая сумма.
 |
 |      Raises:
 |          ValueError: Если сумма превышает баланс.

help() можно вызвать и для конкретного метода:

>>> help(BankAccount.withdraw)

Help on function withdraw in module bank:

withdraw(self, amount: float) -> float
    Снять деньги со счёта.

    Args:
        amount (float): Сумма снятия.

    Returns:
        float: Фактически снятая сумма.

    Raises:
        ValueError: Если сумма превышает баланс.

📄 pydoc — документация из терминала

pydoc — это встроенный модуль Python, который работает прямо из командной строки. Он делает то же самое, что help(), но не требует запускать Python — достаточно написать команду в терминале.

Допустим, у нас есть файл bank.py с нашим классом. Открываем терминал в той же папке:

python -m pydoc bank

python -m pydoc -w bank

📚 Sphinx — профессиональная документация

Вы когда-нибудь читали документацию Django, Flask, NumPy или SQLAlchemy? Все эти сайты с красивыми боковыми панелями, поиском, версиями и примерами кода — они сделаны с помощью Sphinx.

Sphinx — это инструмент, который берёт ваши docstring и генерирует полноценный сайт с документацией. Он поддерживает темы оформления, поиск, кросс-ссылки и множество форматов вывода (HTML, PDF, epub).

🔧 Установка

Sphinx устанавливается через pip — стандартный менеджер пакетов Python:

pip install sphinx

Если вы планируете использовать стиль Google или NumPy для docstring (мы изучили их в предыдущих уроках), установите расширение napoleon:

pip install sphinx sphinx-autodoc-typehints

🚀 Создание проекта документации

Перейдите в папку с вашим проектом и запустите мастер настройки:

sphinx-quickstart docs

Sphinx задаст несколько вопросов: название проекта, имя автора, версия. После ответов создастся папка docs/ со структурой:

docs/
├── conf.py          ← главный файл конфигурации
├── index.rst        ← главная страница документации
├── make.bat         ← для Windows: команды сборки
└── Makefile         ← для Linux/macOS: команды сборки

conf.py — самый важный файл. В нём указываются расширения Sphinx, тема оформления и настройки. Именно здесь вы подключаете autodoc и napoleon.

🧩 Ключевые расширения

Подключаются расширения в conf.py:

# docs/conf.py

extensions = [
    'sphinx.ext.autodoc',    # читает docstring из кода
    'sphinx.ext.napoleon',   # поддержка Google/NumPy стиля
    'sphinx.ext.viewcode',   # ссылки на исходный код
]

🏗️ Сборка документации

После настройки достаточно одной команды:

# Linux / macOS
make -C docs html

# Windows
docs\make.bat html

Sphinx создаст папку docs/_build/html/ с готовым сайтом. Откройте index.html в браузере — и вы увидите профессиональную документацию вашего проекта.

🧠 IDE становится умнее: подсказки из docstring

Документация нужна не только людям. PyCharm, VS Code и другие современные редакторы умеют читать ваши docstring и type hints — и использовать эту информацию, чтобы помогать вам писать код быстрее и с меньшим количеством ошибок.

Представьте: вы создаёте объект вашего класса и начинаете вызывать метод:

account = BankAccount("Иван", 1000)
account.deposit(  # ← нажали открывающую скобку

IDE мгновенно показывает всплывающую подсказку (popup) прямо в редакторе:

Это не магия — IDE просто читает ваш docstring и type hints. Чем лучше документация, тем умнее IDE.

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

# ❌ Версия без документации — IDE ничего не знает
def calculate(x, y):
    return x * y + x

# ✅ Версия с документацией — IDE знает всё!
def calculate(x: float, y: float) -> float:
    """Вычислить результат по формуле x * y + x.

    Args:
        x (float): Первый множитель (основание).
        y (float): Второй множитель (коэффициент).

    Returns:
        float: Результат вычисления.
    """
    return x * y + x

💼 Практический рабочий процесс

Как выглядит использование этих инструментов в реальной работе? Вот типичный сценарий:

📌 Итоги урока