sphinx.ext.napoleon renders Raises section differently than the default format

[anntzer]

Subject: docstrings parsed by sphinx.ext.napoleon use a subtly different markup for documented exceptions.

Problem

(see subject)

Procedure to reproduce the problem

http://www.sphinx-doc.org/en/stable/domains.html?highlight=domains#info-field-lists indicates that exceptions should be documented as

:raises TypeError: if the message_body is not a basestring

but sphinx.ext.napoleon (whether Google or Numpy style) uses a different markup:

In [8]: print(str(sphinxcontrib.napoleon.NumpyDocstring("foo\nRaises\n------\nKeyError\n    oops
    ...: ")))
foo
:raises: :exc:`KeyError` -- oops

In [9]: print(str(sphinxcontrib.napoleon.GoogleDocstring("foo\n\nRaises:\n    KeyError: oops")))
   ...: 
foo

:raises: :exc:`KeyError` -- oops

Expected results

sphinx.ext.napoleon should generate markup similar to the default one. In particular, the current output uses the :exc: interpreted text role, which is only defined by sphinx's python domain, and thus not interpretable by docutils without using sphinx. This is specifically more relevant for projects which would like to parse google/numpy docstrings e.g. with sphinxcontrib.napoleon then feed the results into docutils themselves, without needing sphinx itself (e.g., http://defopt.readthedocs.io/en/latest/).

Reproducible project / your project

N/A

Environment info

• OS: Arch Linux
• Python version: 3.6
• Sphinx version: 1.5.5

[RobRuana]

Ok, yeah this makes sense. I can add a conf flag to choose how exceptions are rendered. I'll probably have time to get to it this weekend.

[anntzer]

Would you accept a patch that unconditionally changes the format to the documented one? That, I can do...

[RobRuana]

Sure, I think that would be a big help. I may end up modifying your patch to add the conf flag. Either way a patch would be a great help.

[anntzer]

What should be the output for this old test case?

                      ("""
Example Function
Raises:
    Invalid Dimensions Error
""", """
Example Function
:raises: Invalid Dimensions Error
"""),

(i.e., how to handle spaces in field name).