mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
d47a7587f9
* rename a few test modules to make the names more consistent * do not copy/use Sphinx from build/ (unnecessary without 2to3) * use a temporary dir for *all* test projects, the source tree will stay pristine that way (default is tests/build) * speed up tests by ~3x by splitting up test projects and avoiding rebuilds
443 lines
10 KiB
Python
443 lines
10 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""
|
|
test_napoleon_docstring
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Tests for :mod:`sphinx.ext.napoleon.docstring` module.
|
|
|
|
|
|
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
|
|
:license: BSD, see LICENSE for details.
|
|
"""
|
|
|
|
import textwrap
|
|
from unittest import TestCase
|
|
|
|
from sphinx.ext.napoleon import Config
|
|
from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
|
|
from util import mock
|
|
|
|
|
|
class BaseDocstringTest(TestCase):
|
|
pass
|
|
|
|
|
|
class GoogleDocstringTest(BaseDocstringTest):
|
|
docstrings = [(
|
|
"""Single line summary""",
|
|
"""Single line summary"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Extended description
|
|
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
Extended description
|
|
"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Args:
|
|
arg1(str):Extended
|
|
description of arg1
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:Parameters: **arg1** (*str*) --
|
|
Extended
|
|
description of arg1"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Args:
|
|
arg1(str):Extended
|
|
description of arg1
|
|
arg2 ( int ) : Extended
|
|
description of arg2
|
|
|
|
Keyword Args:
|
|
kwarg1(str):Extended
|
|
description of kwarg1
|
|
kwarg2 ( int ) : Extended
|
|
description of kwarg2""",
|
|
"""
|
|
Single line summary
|
|
|
|
:Parameters: * **arg1** (*str*) --
|
|
Extended
|
|
description of arg1
|
|
* **arg2** (*int*) --
|
|
Extended
|
|
description of arg2
|
|
|
|
:Keyword Arguments: * **kwarg1** (*str*) --
|
|
Extended
|
|
description of kwarg1
|
|
* **kwarg2** (*int*) --
|
|
Extended
|
|
description of kwarg2"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Arguments:
|
|
arg1(str):Extended
|
|
description of arg1
|
|
arg2 ( int ) : Extended
|
|
description of arg2
|
|
|
|
Keyword Arguments:
|
|
kwarg1(str):Extended
|
|
description of kwarg1
|
|
kwarg2 ( int ) : Extended
|
|
description of kwarg2""",
|
|
"""
|
|
Single line summary
|
|
|
|
:Parameters: * **arg1** (*str*) --
|
|
Extended
|
|
description of arg1
|
|
* **arg2** (*int*) --
|
|
Extended
|
|
description of arg2
|
|
|
|
:Keyword Arguments: * **kwarg1** (*str*) --
|
|
Extended
|
|
description of kwarg1
|
|
* **kwarg2** (*int*) --
|
|
Extended
|
|
description of kwarg2"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Return:
|
|
str:Extended
|
|
description of return value
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:returns: *str* --
|
|
Extended
|
|
description of return value"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Returns:
|
|
str:Extended
|
|
description of return value
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:returns: *str* --
|
|
Extended
|
|
description of return value"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Returns:
|
|
Extended
|
|
description of return value
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:returns: Extended
|
|
description of return value"""
|
|
)]
|
|
|
|
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), config))
|
|
expected = textwrap.dedent(expected)
|
|
self.assertEqual(expected, actual)
|
|
|
|
def test_parameters_with_class_reference(self):
|
|
docstring = """\
|
|
Construct a new XBlock.
|
|
|
|
This class should only be used by runtimes.
|
|
|
|
Arguments:
|
|
runtime (:class:`Runtime`): Use it to access the environment.
|
|
It is available in XBlock code as ``self.runtime``.
|
|
|
|
field_data (:class:`FieldData`): Interface used by the XBlock
|
|
fields to access their data from wherever it is persisted.
|
|
|
|
scope_ids (:class:`ScopeIds`): Identifiers needed to resolve scopes.
|
|
|
|
"""
|
|
|
|
actual = str(GoogleDocstring(docstring))
|
|
expected = """\
|
|
Construct a new XBlock.
|
|
|
|
This class should only be used by runtimes.
|
|
|
|
:param runtime: Use it to access the environment.
|
|
It is available in XBlock code as ``self.runtime``.
|
|
|
|
:type runtime: :class:`Runtime`
|
|
:param field_data: Interface used by the XBlock
|
|
fields to access their data from wherever it is persisted.
|
|
|
|
:type field_data: :class:`FieldData`
|
|
:param scope_ids: Identifiers needed to resolve scopes.
|
|
|
|
:type scope_ids: :class:`ScopeIds`
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
def test_attributes_with_class_reference(self):
|
|
docstring = """\
|
|
Attributes:
|
|
in_attr(:class:`numpy.ndarray`): super-dooper attribute
|
|
"""
|
|
|
|
actual = str(GoogleDocstring(docstring))
|
|
expected = """\
|
|
.. attribute:: in_attr
|
|
|
|
:class:`numpy.ndarray`
|
|
|
|
super-dooper attribute
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
docstring = """\
|
|
Attributes:
|
|
in_attr(numpy.ndarray): super-dooper attribute
|
|
"""
|
|
|
|
actual = str(GoogleDocstring(docstring))
|
|
expected = """\
|
|
.. attribute:: in_attr
|
|
|
|
*numpy.ndarray*
|
|
|
|
super-dooper attribute
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
|
|
class NumpyDocstringTest(BaseDocstringTest):
|
|
docstrings = [(
|
|
"""Single line summary""",
|
|
"""Single line summary"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Extended description
|
|
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
Extended description
|
|
"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Parameters
|
|
----------
|
|
arg1:str
|
|
Extended
|
|
description of arg1
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:Parameters: **arg1** (*str*) --
|
|
Extended
|
|
description of arg1"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Parameters
|
|
----------
|
|
arg1:str
|
|
Extended
|
|
description of arg1
|
|
arg2 : int
|
|
Extended
|
|
description of arg2
|
|
|
|
Keyword Arguments
|
|
-----------------
|
|
kwarg1:str
|
|
Extended
|
|
description of kwarg1
|
|
kwarg2 : int
|
|
Extended
|
|
description of kwarg2
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:Parameters: * **arg1** (*str*) --
|
|
Extended
|
|
description of arg1
|
|
* **arg2** (*int*) --
|
|
Extended
|
|
description of arg2
|
|
|
|
:Keyword Arguments: * **kwarg1** (*str*) --
|
|
Extended
|
|
description of kwarg1
|
|
* **kwarg2** (*int*) --
|
|
Extended
|
|
description of kwarg2"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Return
|
|
------
|
|
str
|
|
Extended
|
|
description of return value
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:returns: *str* --
|
|
Extended
|
|
description of return value"""
|
|
), (
|
|
"""
|
|
Single line summary
|
|
|
|
Returns
|
|
-------
|
|
str
|
|
Extended
|
|
description of return value
|
|
""",
|
|
"""
|
|
Single line summary
|
|
|
|
:returns: *str* --
|
|
Extended
|
|
description of return value"""
|
|
)]
|
|
|
|
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), 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(docstring, config))
|
|
expected = """\
|
|
:Parameters: **param1** (:class:`MyClass <name.space.MyClass>` instance)
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
config = Config(napoleon_use_param=True)
|
|
actual = str(NumpyDocstring(docstring, config))
|
|
expected = """\
|
|
|
|
: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(docstring, config))
|
|
expected = """\
|
|
:Parameters: **param1** (*MyClass instance*)
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
config = Config(napoleon_use_param=True)
|
|
actual = str(NumpyDocstring(textwrap.dedent(docstring), config))
|
|
expected = """\
|
|
|
|
:type param1: MyClass instance
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
def test_see_also_refs(self):
|
|
docstring = """\
|
|
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
|
|
|
See Also
|
|
--------
|
|
some, other, funcs
|
|
otherfunc : relationship
|
|
|
|
"""
|
|
|
|
actual = str(NumpyDocstring(docstring))
|
|
|
|
expected = """\
|
|
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
|
|
|
.. seealso::
|
|
|
|
:obj:`some`, :obj:`other`, :obj:`funcs`
|
|
\n\
|
|
:obj:`otherfunc`
|
|
relationship
|
|
"""
|
|
self.assertEqual(expected, actual)
|
|
|
|
docstring = """\
|
|
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
|
|
|
See Also
|
|
--------
|
|
some, other, funcs
|
|
otherfunc : relationship
|
|
|
|
"""
|
|
|
|
config = Config()
|
|
app = mock.Mock()
|
|
actual = str(NumpyDocstring(docstring, config, app, "method"))
|
|
|
|
expected = """\
|
|
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
|
|
|
|
.. seealso::
|
|
|
|
:meth:`some`, :meth:`other`, :meth:`funcs`
|
|
\n\
|
|
:meth:`otherfunc`
|
|
relationship
|
|
"""
|
|
self.assertEqual(expected, actual)
|