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?
Answers:
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
"""
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.
"""
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)
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)
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 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
"""
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.
"""
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)
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)