diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 2aad7102f..ee4df271c 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -50,7 +50,7 @@ _token_regex = re.compile( r'|"(?:\\"|[^"])*"' r"|'(?:\\'|[^'])*')" ) -_singletons = ("None", "True", "False", "...", "Ellipsis") +_singletons = ("None", "True", "False", "Ellipsis") class GoogleDocstring: @@ -924,6 +924,9 @@ def _convert_numpy_type_spec(_type: str, location: str = None, translations: dic # use :class: (the default) only if obj is not a standard singleton if translation in _singletons and default_translation == ":class:`%s`": default_translation = ":obj:`%s`" + elif translation == "..." and default_translation == ":class:`%s`": + # allow referencing the builtin ... + default_translation = ":obj:`%s `" if _xref_regex.match(translation) is None: translation = default_translation % translation diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index c99aae867..b5c079314 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -2128,7 +2128,7 @@ definition_after_normal_text : int ---------- param1 : DataFrame the data to work on - param2 : int or float or None or ..., optional + param2 : int or float or None, optional a parameter with different types param3 : dict-like, optional a optional mapping @@ -2140,12 +2140,14 @@ definition_after_normal_text : int different default format param7 : mapping of hashable to str, optional a optional mapping + param8 : ... or Ellipsis + ellipsis """) expected = dedent("""\ :param param1: the data to work on :type param1: DataFrame :param param2: a parameter with different types - :type param2: :class:`int` or :class:`float` or :obj:`None` or :obj:`...`, *optional* + :type param2: :class:`int` or :class:`float` or :obj:`None`, *optional* :param param3: a optional mapping :type param3: :term:`dict-like `, *optional* :param param4: a optional parameter with different types @@ -2156,6 +2158,8 @@ definition_after_normal_text : int :type param6: :class:`int`, *default* :obj:`None` :param param7: a optional mapping :type param7: :term:`mapping` of :term:`hashable` to :class:`str`, *optional* + :param param8: ellipsis + :type param8: :obj:`... ` or :obj:`Ellipsis` """) translations = { "dict-like": ":term:`dict-like `",