Commits

Rob Ruana  committed c3b5cea

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.

  • Participants
  • Parent commits 6df0912

Comments (0)

Files changed (5)

File doc/ext/napoleon.rst

     napoleon_use_admonition_for_notes = False
     napoleon_use_admonition_for_references = False
     napoleon_use_ivar = False
-    napoleon_use_param = False
-    napoleon_use_rtype = False
+    napoleon_use_param = True
+    napoleon_use_rtype = True
 
 .. _Google style:
    http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 
    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::
 
 .. 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::
 

File sphinx/ext/napoleon/__init__.py

         napoleon_use_admonition_for_notes = False
         napoleon_use_admonition_for_references = False
         napoleon_use_ivar = False
-        napoleon_use_param = False
-        napoleon_use_rtype = False
+        napoleon_use_param = True
+        napoleon_use_rtype = True
 
     .. _Google style:
        http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 
                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.
 
                          * **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.
 
         '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_rtype': (False, 'env'),
+        'napoleon_use_param': (True, 'env'),
+        'napoleon_use_rtype': (True, 'env'),
     }
 
     def __init__(self, **settings):

File sphinx/ext/napoleon/docstring.py

         separator = any([s for s in _desc]) and ' --' or ''
         if _name:
             if _type:
-                field = ['**%s** (*%s*)%s' % (_name, _type, separator)]
+                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:
-            field = ['*%s*%s' % (_type, separator)]
+            if '`' in _type:
+                field = ['%s%s' % (_type, separator)]
+            else:
+                field = ['*%s*%s' % (_type, separator)]
         else:
             field = []
         return field + _desc
                 else:
                     _name = ':exc:`%s`' % _name
                 if _type:
-                    field = ['%s (*%s*)%s' % (_name, _type, sep)]
+                    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:
-                field = ['*%s*%s' % (_type, sep)]
+                if '`' in _type:
+                    field = ['%s%s' % (_type, sep)]
+                else:
+                    field = ['*%s*%s' % (_type, sep)]
             else:
                 field = []
             field = field + _desc

File tests/test_napoleon.py

 
         expected = ['Summary line.',
                     '',
-                    ':Parameters: **arg1** --',
-                    '             arg1 description']
+                    ':param arg1: arg1 description',
+                    '']
         self.assertEqual(expected, lines)
 
 

File tests/test_napoleon_docstring.py

 """
 
 import textwrap
+from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from unittest import TestCase
 
     )]
 
     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)
 
     )]
 
     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)