Группировка параметров функции с помощью sphinx

Чтобы сгруппировать параметры функции в документации Sphinx на персидском языке, мы должны сначала ознакомиться с концепцией группировки параметров и использованием стандартного шаблона документации в Sphinx. Этот инструмент широко используется для документирования проектов программирования, особенно на языке Python. Оставайтесь с Radib до конца этого руководства.

В Sphinx мы используем формат reStructuredText (rst.) и плагины, такие как autodoc, для автоматического создания документации из исходного кода. Одной из важных особенностей этого формата является подробное и структурированное объяснение параметров, возвращаемых значений и исключений функций.

1. Основная структура документации параметров функций в Sphinx

Для документирования функции в Sphinx можно использовать следующий синтаксис:

def sample_function(param1: int, param2: str, param3: bool = True) -> str:
    """
    Краткое описание функции.

    :param param1: Целочисленный входной параметр
    :type param1: int
    :param param2: Строка, передаваемая в функцию
    :type param2: str
    :param param3: Логическое значение по умолчанию
    :type param3: bool
    :return: Строка на выходе
    :rtype: str
    """
    return f"{param1} - {param2} - {param3}"

В этом примере:

• :param используется для описания каждого параметра.
• :type определяет тип параметра.
• Описание после этих тегов объясняет роль каждого параметра.
• :return: объясняет возвращаемое значение, а :rtype: указывает его тип.

2. Группировка параметров в документации

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

Купите виртуальный сервер с лучшим качеством и ценой в Radib, нажмите здесь

Пример ручной группировки:

def configure_server(ip_address: str, port: int, timeout: int, retry: bool, log_level: str):
    """
    Конфигурация сервера

    **Сетевые параметры:**
    :param ip_address: IP-адрес сервера
    :type ip_address: str
    :param port: Порт связи
    :type port: int

    **Настройки подключения:**
    :param timeout: Тайм-аут в секундах
    :type timeout: int
    :param retry: Повторить запрос или нет
    :type retry: bool

    **Настройки логирования:**
    :param log_level: Уровень логирования (DEBUG, INFO, ERROR)
    :type log_level: str
    """
    pass

В этом примере используются текстовые описания (**Заголовок раздела:**) для группировки параметров. Это простой и эффективный метод.

3. Использование тегов sphinx.ext.napoleon

Расширение napoleon в Sphinx позволяет документировать в стиле Google или NumPy, что обеспечивает лучшую поддержку группировки параметров.

Пример в стиле Google:

def database_connection(host: str, port: int, username: str, password: str, use_ssl: bool) -> bool:
    """
    Подключение к базе данных.

    Args:
        host (str): Адрес сервера базы данных
        port (int): Порт подключения
        username (str): Имя пользователя
        password (str): Пароль
        use_ssl (bool): Установить безопасное подключение

    Returns:
        bool: Статус успешного подключения
    """
    return True

4. Активация расширения napoleon

Чтобы активировать это расширение, откройте файл conf.py в Sphinx и добавьте следующую строку:

extensions = ['sphinx.ext.napoleon']

5. Автоматическая генерация документации с помощью autodoc

Если вы хотите автоматически генерировать документацию из кода, выполните следующую команду:

sphinx-apidoc -o docs/ your_project/

Заключение

Сочетая ручные методы и расширение napoleon в Sphinx, вы можете создавать точную, читаемую и структурированную документацию для функций и классов. Если вы работаете над крупным проектом, рекомендуется использовать napoleon для упрощения процесса документирования.