如何使用Sphinx记录异常？

Question

我似乎无法弄清楚如何使用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.
    """

Sphinx一直在说：

“字段列表未以空行结束；意外取消缩进。”

那我该如何消除这个消息，以及如何正确地记录可能有多个行文档的多个异常？

- siebz0r

---

这个问题不是关于记录异常的，对吧？需要编辑吗？ - joel

有关此问题的文档遍布网络，例如 https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html。 - YBrush

Answer 1

您可以使用反斜杠进行行的续接：

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

更新：

缩进似乎可以代替转义换行符：

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

- ecatmur

---

我稍微编辑了一下语法，Sphinx似乎使用它可以得到最好的结果。但我无法避免感觉反斜杠有点像hackish。 - siebz0r

似乎不再需要反斜杠了。我已经相应地更新了答案。 - siebz0r

@siebz0r：反斜杠是一种极其粗糙的hack，即使使用（some_funct）等辅助函数也会很丑陋。它在某些情况下无法正常工作。 - László Papp

Answer 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有一些不错的示例（可惜没有多行异常）。

- Paul-Armand Verhaegen

Answer 3

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

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

    """

（请注意末尾的空行）

- ms09

---

末尾有一个空行，但仍报错。 - NelsonGon

Answer 4

这给我带来了一些美好的东西。

你忘了在异常名称前面加上 :。

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

- ornoone

---

使用这个方法，Sphinx 就不会再抱怨缩进了，输出看起来也很好，但是异常名称的大小写会丢失。例如，IOException 变成了 Ioexception。 - siebz0r