Closes #1396: Param types with inline markup no longer italicized

Napoleon was attempting to render nested inline markup
( [a big no-no!](http://sphinx-doc.org/rest.html) ) for
parameter types. Now, if Napoleon sees any backquotes
in the parameter type, it is rendered without italics.

doc/ext/napoleon.rst

@@ -197,8 +197,8 @@ enabled in `conf.py`::
     napoleon_use_admonition_for_notes = False
     napoleon_use_admonition_for_references = False
     napoleon_use_ivar = False
-    napoleon_use_param = False
+    napoleon_use_param = True
-    napoleon_use_rtype = False
+    napoleon_use_rtype = True
 
 .. _Google style:
    http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
@@ -328,7 +328,7 @@ enabled in `conf.py`::
 
    True to use a ``:param:`` role for each function parameter. False to
    use a single ``:parameters:`` role for all the parameters.
-   *Defaults to False.*
+   *Defaults to True.*
 
    This `NumPy style`_ snippet will be converted as follows::
 
@@ -356,7 +356,7 @@ enabled in `conf.py`::
 .. confval:: napoleon_use_rtype
 
    True to use the ``:rtype:`` role for the return type. False to output
-   the return type inline with the description. *Defaults to False.*
+   the return type inline with the description. *Defaults to True.*
 
    This `NumPy style`_ snippet will be converted as follows::
 

sphinx/ext/napoleon/__init__.py

@@ -35,8 +35,8 @@ class Config(object):
         napoleon_use_admonition_for_notes = False
         napoleon_use_admonition_for_references = False
         napoleon_use_ivar = False
-        napoleon_use_param = False
+        napoleon_use_param = True
-        napoleon_use_rtype = False
+        napoleon_use_rtype = True
 
     .. _Google style:
        http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
@@ -152,7 +152,7 @@ class Config(object):
 
                Description of `attr1`
 
-    napoleon_use_param : bool, defaults to False
+    napoleon_use_param : bool, defaults to True
         True to use a ``:param:`` role for each function parameter. False to
         use a single ``:parameters:`` role for all the parameters.
 
@@ -179,7 +179,7 @@ class Config(object):
                          * **arg2** (*int, optional*) --
                            Description of `arg2`, defaults to 0
 
-    napoleon_use_rtype : bool, defaults to False
+    napoleon_use_rtype : bool, defaults to True
         True to use the ``:rtype:`` role for the return type. False to output
         the return type inline with the description.
 
@@ -209,8 +209,8 @@ class Config(object):
         'napoleon_use_admonition_for_notes': (False, 'env'),
         'napoleon_use_admonition_for_references': (False, 'env'),
         'napoleon_use_ivar': (False, 'env'),
-        'napoleon_use_param': (False, 'env'),
+        'napoleon_use_param': (True, 'env'),
-        'napoleon_use_rtype': (False, 'env'),
+        'napoleon_use_rtype': (True, 'env'),
     }
 
     def __init__(self, **settings):

sphinx/ext/napoleon/docstring.py

@@ -292,10 +292,16 @@ class GoogleDocstring(object):
         separator = any([s for s in _desc]) and ' --' or ''
         if _name:
             if _type:
+                if '`' in _type:
+                    field = ['**%s** (%s)%s' % (_name, _type, separator)]
+                else:
                     field = ['**%s** (*%s*)%s' % (_name, _type, separator)]
             else:
                 field = ['**%s**%s' % (_name, separator)]
         elif _type:
+            if '`' in _type:
+                field = ['%s%s' % (_type, separator)]
+            else:
                 field = ['*%s*%s' % (_type, separator)]
         else:
             field = []
@@ -483,10 +489,16 @@ class GoogleDocstring(object):
                 else:
                     _name = ':exc:`%s`' % _name
                 if _type:
+                    if '`' in _type:
+                        field = ['%s (%s)%s' % (_name, _type, sep)]
+                    else:
                         field = ['%s (*%s*)%s' % (_name, _type, sep)]
                 else:
                     field = ['%s%s' % (_name, sep)]
             elif _type:
+                if '`' in _type:
+                    field = ['%s%s' % (_type, sep)]
+                else:
                     field = ['*%s*%s' % (_type, sep)]
             else:
                 field = []

tests/test_napoleon.py

@@ -84,8 +84,8 @@ class ProcessDocstringTest(TestCase):
 
         expected = ['Summary line.',
                     '',
-                    ':Parameters: **arg1** --',
+                    ':param arg1: arg1 description',
-                    '             arg1 description']
+                    '']
         self.assertEqual(expected, lines)
 
 

tests/test_napoleon_docstring.py

@@ -11,6 +11,7 @@
 """
 
 import textwrap
+from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from unittest import TestCase
 
@@ -142,8 +143,9 @@ class GoogleDocstringTest(BaseDocstringTest):
     )]
 
     def test_docstrings(self):
+        config = Config(napoleon_use_param=False, napoleon_use_rtype=False)
         for docstring, expected in self.docstrings:
-            actual = str(GoogleDocstring(textwrap.dedent(docstring)))
+            actual = str(GoogleDocstring(textwrap.dedent(docstring), config))
             expected = textwrap.dedent(expected)
             self.assertEqual(expected, actual)
 
@@ -253,7 +255,54 @@ class NumpyDocstringTest(BaseDocstringTest):
     )]
 
     def test_docstrings(self):
+        config = Config(napoleon_use_param=False, napoleon_use_rtype=False)
         for docstring, expected in self.docstrings:
-            actual = str(NumpyDocstring(textwrap.dedent(docstring)))
+            actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
             expected = textwrap.dedent(expected)
             self.assertEqual(expected, actual)
+
+    def test_parameters_with_class_reference(self):
+        docstring = """
+            Parameters
+            ----------
+            param1 : :class:`MyClass <name.space.MyClass>` instance
+
+            """
+
+        config = Config(napoleon_use_param=False)
+        actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
+        expected = textwrap.dedent("""
+            :Parameters: **param1** (:class:`MyClass <name.space.MyClass>` instance)
+            """)
+        self.assertEqual(expected, actual)
+
+        config = Config(napoleon_use_param=True)
+        actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
+        expected = textwrap.dedent("""
+
+            :type param1: :class:`MyClass <name.space.MyClass>` instance
+            """)
+        self.assertEqual(expected, actual)
+
+    def test_parameters_without_class_reference(self):
+        docstring = """
+            Parameters
+            ----------
+            param1 : MyClass instance
+
+            """
+
+        config = Config(napoleon_use_param=False)
+        actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
+        expected = textwrap.dedent("""
+            :Parameters: **param1** (*MyClass instance*)
+            """)
+        self.assertEqual(expected, actual)
+
+        config = Config(napoleon_use_param=True)
+        actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
+        expected = textwrap.dedent("""
+
+            :type param1: MyClass instance
+            """)
+        self.assertEqual(expected, actual)