How to document an exception using Sphinx?

siebz0r picture siebz0r · Apr 12, 2013 · Viewed 15k times · Source

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?

Answer

ecatmur picture ecatmur · Apr 12, 2013

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.
    """