如何使用 Sphinx 记录异常？答案

【问题标题】：How to document an exception using Sphinx?如何使用 Sphinx 记录异常？
【发布时间】：2013-04-12 13:22:50
【问题描述】：

我似乎不知道如何使用 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.
    """

斯芬克斯一直在说：

“字段列表结束时没有空行；意外取消缩进。”

那么我该如何摆脱该消息以及使用多行文档记录可能的多个异常的正确方法是什么？

【问题讨论】：

这个问题并不是关于记录异常，不是吗？应该编辑吗？

标签： python exception python-sphinx

【解决方案1】：

您可以使用反斜杠来续行：

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

更新：

缩进似乎有效，而不是转义换行：

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

【讨论】：

我稍微编辑了语法，Sphinx 似乎给出了最好的结果。我不禁觉得反斜杠很老套。
似乎不再需要反斜杠了。我已经相应地更新了答案。
@siebz0r: 反斜杠是一个巨大的黑客，例如在帮助（some_funct）的帮助下会很丑。它不会在所有情况下都很好地工作。

【解决方案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
    """

【讨论】：

使用这个，Sphinx 停止抱怨缩进并且输出看起来相当不错，但是异常名称丢失了它的大小写。例如IOException 变为 Ioexception。

【解决方案4】：

我认为有一个样本不会让 Sphinx 抱怨：

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

    """

（注意最后的空行）

【讨论】：

最后有一个空行。仍然抱怨。