Какие существуют основные стили оформления docstring в Python?

В Python существует несколько общепринятых стилей оформления docstrings, которые стандартизируют документирование кода и позволяют инструментам вроде Sphinx автоматически генерировать документацию. Основные из них:

1. Google Style

Отличается высокой читаемостью благодаря четким разделам (Args, Returns, Raises).

def my_function(arg1: int, arg2: str) -> bool:
    """Краткое описание функции в одну строку.

    Более подробное описание, если необходимо.

    Args:
        arg1 (int): Описание первого аргумента.
        arg2 (str): Описание второго аргумента.

    Returns:
        bool: Описание того, что функция возвращает.
    """
    return True

2. reStructuredText (reST)

Официальный стиль для документации самого Python, широко используется Sphinx. Синтаксис более строгий.

def my_function(arg1: int, arg2: str) -> bool:
    """Краткое описание функции в одну строку.

    :param arg1: Описание первого аргумента.
    :type arg1: int
    :param arg2: Описание второго аргумента.
    :type arg2: str
    :return: Описание того, что функция возвращает.
    :rtype: bool
    """
    return True

3. NumPy/SciPy Style

Очень подробный и структурированный формат, популярный в научных и data-science библиотеках. Требует точного форматирования.

def my_function(arg1, arg2):
    """Краткое описание функции в одну строку.

    Parameters
    ----------
    arg1 : int
        Описание первого аргумента.
    arg2 : str
        Описание второго аргумента.

    Returns
    -------
    bool
        Описание того, что функция возвращает.
    """
    return True

Выбор стиля часто диктуется стандартами команды или проекта. Google и NumPy стили особенно популярны благодаря их читаемости и отличной поддержке современными инструментами.