How to document an exception using Sphinx?

Question

I can't seem to figure out how to document exceptions using Sphinx.

I've tried the following:

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 keeps saying:

"Field list ends without a blank line; unexpected unindent."

So how do I get rid of the message and what is the proper way to document possibly multiple exceptions with multiple-line documentation?

Solution 1

You can use a backslash for line continuation:

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

Update:

Indenting seems to work instead of escaping the newline:

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

Solution 2

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

        :raise: Exception

            when status != my_status 
            | status <= max_status

Note: https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example has some nice samples (not on the multi-line exception unfortunately)

Comments

[siebz0r]

Using this, Sphinx stops complaining about the indent and the output looks quite nice, but the exception name loses it's casing. e.g. IOException becomes Ioexception.

[siebz0r]

I've edited the syntax a bit, Sphinx seems to give the best results with that. I can't help feeling like the backslash is quite hackish.

[siebz0r]

It seems that the backslash isn't needed anymore. I've updated the answer accordingly.

[László Papp]

@siebz0r: backslash is a tremendeous hack, and will be ugly with help (some_funct) for instance. It will not work nicely in all cases.

[NelsonGon]

Had a blank line at the end. Still complained.