IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Rob Ruana 2014-03-09 01:56:56 -05:00
parent b97d01308c
commit 18df6421bf
5 changed files with 79 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/ext/napoleon.rst
View File

@ -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_rtype = False
napoleon_use_param = True
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::

12
sphinx/ext/napoleon/__init__.py
View File

@ -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_rtype = False
napoleon_use_param = True
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_rtype': (False, 'env'),
'napoleon_use_param': (True, 'env'),
'napoleon_use_rtype': (True, 'env'),
}
def __init__(self, **settings):

20
sphinx/ext/napoleon/docstring.py
View File

@ -292,11 +292,17 @@ class GoogleDocstring(object):
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
@ -483,11 +489,17 @@ class GoogleDocstring(object):
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

4
tests/test_napoleon.py
View File

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

53
tests/test_napoleon_docstring.py
View File

@ -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)