Как документировать исключение, используя Sphinx

Я не могу понять, как документировать исключения с помощью Sphinx.

Я пробовал следующее:

def some_funct():
    """
    :raises: ExceptionType: Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises: ExceptionType, Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises ExceptionType: Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises:
        ExceptionType: Some multi-line
            exception description.
    """

Сфинкс говорит: "Список полей заканчивается без пустой строки, непредвиденный". Итак, как мне избавиться от сообщения и как правильно документировать, возможно, несколько исключений с многострочной документацией?

Ответ 1

Вы можете использовать обратную косую черту для продолжения строки:

def some_funct():
    """
    :raises ExceptionType: Some multi-line \
        exception description.
    """

Update:

Отступы, кажется, работают вместо того, чтобы ускользнуть от новой строки:

def some_funct():
    """
    :raises ExceptionType: Some multi-line
        exception description.
    """

Ответ 2

def some_funct():
    """
    My documentation, but watch the empty line below (necessary)

        :raise: Exception

            when status != my_status 
            | status <= max_status

Примечание: https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example содержит несколько хороших образцов (к сожалению, не к многострочному исключению)

Ответ 3

это мне хорошо.

вы забудете : Перед именем исключения

def some_funct():
    """
    :raise: 
        :IOException: a probleme occured
                      and it can't be passed
    """