mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
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.
This commit is contained in:
parent
b97d01308c
commit
18df6421bf
@ -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::
|
||||
|
||||
|
@ -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):
|
||||
|
@ -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
|
||||
|
@ -84,8 +84,8 @@ class ProcessDocstringTest(TestCase):
|
||||
|
||||
expected = ['Summary line.',
|
||||
'',
|
||||
':Parameters: **arg1** --',
|
||||
' arg1 description']
|
||||
':param arg1: arg1 description',
|
||||
'']
|
||||
self.assertEqual(expected, lines)
|
||||
|
||||
|
||||
|
@ -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)
|
||||
|
Loading…
Reference in New Issue
Block a user