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?

this question isn't really about documenting exceptions, no? should be edited? — joel, Apr 29 '20 at 20:01
There are **so many documentations** about it out there, like https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html. — YBrush, Aug 02 '22 at 07:49

score 43 · Accepted Answer · edited Oct 30 '13 at 12:30

43

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

edited Oct 30 '13 at 12:30

siebz0r

18,867
14
64
107

answered Apr 12 '13 at 14:04

ecatmur

152,476
27
293
366

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 Apr 13 '13 at 15:00
It seems that the backslash isn't needed anymore. I've updated the answer accordingly. – siebz0r Oct 30 '13 at 12:31
@siebz0r: backslash is a tremendeous hack, and will be ugly with help (some_funct) for instance. It will not work nicely in all cases. – László Papp Sep 08 '14 at 16:17

Paul-Armand Verhaegen · Answer 2 · 2014-10-08T11:01:18.680

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)

edited Oct 08 '14 at 11:01

answered Oct 08 '14 at 10:56

Paul-Armand Verhaegen

537
5
9

score 0 · Answer 3 · edited Sep 19 '17 at 12:35

0

this give me somthing nice.

you forget the : Before the exception name

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

edited Sep 19 '17 at 12:35

dogmatic69

7,574
4
31
49

answered Apr 12 '13 at 13:36

ornoone

651
5
11

1

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 Apr 12 '13 at 13:49

score 0 · Answer 4 · answered Sep 25 '18 at 12:39

0

I think there's a sample that wouldn't make Sphinx complain:

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

    """

(note the blank line at the end)

answered Sep 25 '18 at 12:39

ms09

1

Had a blank line at the end. Still complained. – NelsonGon Aug 11 '20 at 01:03

How to document an exception using Sphinx?

4 Answers4