From 4d36cccd742e27531d78a69dc7b3977c9bfdb329 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 8 Jun 2020 13:43:09 +0200 Subject: escape combined args and kwargs for numpy docstrings --- sphinx/ext/napoleon/docstring.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 32edd7f8f..228b8859e 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -876,6 +876,16 @@ class NumpyDocstring(GoogleDocstring): self._directive_sections = ['.. index::'] super().__init__(docstring, config, app, what, name, obj, options) + def _escape_args_and_kwargs(self, name): + if ", " in name: + parts = name.split(", ") + return ", ".join( + super()._escape_args_and_kwargs(part) + for part in parts + ) + + return super()._escape_args_and_kwargs(name) + def _consume_field(self, parse_type: bool = True, prefer_type: bool = False ) -> Tuple[str, str, List[str]]: line = next(self._line_iter) -- cgit v1.2.1 From 15b443c074e2c584e8b3779d174e091cfcaeb729 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 8 Jun 2020 13:52:46 +0200 Subject: add a test for combined args and kwargs --- tests/test_ext_napoleon_docstring.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 738fd6532..879a2aaa4 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -1189,6 +1189,23 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary + Parameters + ---------- + arg1:str + Extended description of arg1 + *args, **kwargs: + Variable length argument list and arbitrary keyword arguments. + """, + """ + Single line summary + + :Parameters: * **arg1** (*str*) -- Extended description of arg1 + * **\\*args, \\*\\*kwargs** -- Variable length argument list and arbitrary keyword arguments. + """ + ), ( + """ + Single line summary + Yield ----- str -- cgit v1.2.1 From d5f552685c42264bf9bdb5a32d692fa7688c1f81 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 8 Jun 2020 13:53:11 +0200 Subject: use a alias of the implementation of the base class and add type hints --- sphinx/ext/napoleon/docstring.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 228b8859e..e6f2c2998 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -876,15 +876,14 @@ class NumpyDocstring(GoogleDocstring): self._directive_sections = ['.. index::'] super().__init__(docstring, config, app, what, name, obj, options) - def _escape_args_and_kwargs(self, name): + def _escape_args_and_kwargs(self, name: str) -> str: + func = super()._escape_args_and_kwargs + if ", " in name: parts = name.split(", ") - return ", ".join( - super()._escape_args_and_kwargs(part) - for part in parts - ) + return ", ".join(func(part) for part in parts) - return super()._escape_args_and_kwargs(name) + return func(name) def _consume_field(self, parse_type: bool = True, prefer_type: bool = False ) -> Tuple[str, str, List[str]]: -- cgit v1.2.1 From 95ec45b562392c63c7d1eddd945eaf177b4f747d Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 8 Jun 2020 14:19:03 +0200 Subject: check that we can only combine *args with **kwargs and vice versa --- sphinx/ext/napoleon/docstring.py | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index e6f2c2998..2fa40ddb2 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -18,13 +18,16 @@ from typing import Any, Callable, Dict, List, Tuple, Union from sphinx.application import Sphinx from sphinx.config import Config as SphinxConfig from sphinx.ext.napoleon.iterators import modify_iter -from sphinx.locale import _ +from sphinx.locale import _, __ +from sphinx.util import logging if False: # For type annotation from typing import Type # for python3.5.1 +logger = logging.getLogger(__name__) + _directive_regex = re.compile(r'\.\. \S+::') _google_section_regex = re.compile(r'^(\s|\w)+:\s*$') _google_typed_arg_regex = re.compile(r'\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)') @@ -880,8 +883,30 @@ class NumpyDocstring(GoogleDocstring): func = super()._escape_args_and_kwargs if ", " in name: - parts = name.split(", ") - return ", ".join(func(part) for part in parts) + args, kwargs, *rest = name.split(", ") + + is_args = args[:1] == "*" and len([c for c in args if c == "*"]) == 1 + is_kwargs = kwargs[:2] == "**" and len([c for c in kwargs if c == "*"]) == 2 + + if is_args or is_kwargs and not (is_args and is_kwargs): + name_ = args if is_args else kwargs + other = "*args" if not is_args else "**kwargs" + logger.warning( + __("can only combine parameters of form %s with %s: %s"), + name_, + other, + name, + location=None, + ) + elif is_args and is_kwargs and rest: + logger.warning( + __("cannot combine %s and %s with more parameters: %s"), + args, + kwargs, + name, + location=None, + ) + return ", ".join([func(args), func(kwargs)]) return func(name) -- cgit v1.2.1 From 0adc7999f747d75dd37c9b0ab1b1f2c5e69d738b Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 12 Jul 2020 01:29:38 +0200 Subject: add location information and make sure args and kwargs cannot be swapped --- sphinx/ext/napoleon/docstring.py | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 2fa40ddb2..1eb0a35cb 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -885,10 +885,24 @@ class NumpyDocstring(GoogleDocstring): if ", " in name: args, kwargs, *rest = name.split(", ") - is_args = args[:1] == "*" and len([c for c in args if c == "*"]) == 1 - is_kwargs = kwargs[:2] == "**" and len([c for c in kwargs if c == "*"]) == 2 + def check_args(s): + return s[:1] == "*" and len([c for c in s if c == "*"]) == 1 - if is_args or is_kwargs and not (is_args and is_kwargs): + def check_kwargs(s): + return s[:2] == "**" and len([c for c in s if c == "*"]) == 2 + + is_args = check_args(args) + is_kwargs = check_kwargs(kwargs) + + location_name = "docstring of {}".format(self._name) + location = ":".join([self._obj.__code__.co_filename, location_name, ""]) + if check_args(kwargs) or check_kwargs(args): + logger.warning( + __("wrong order of *args and **kwargs: %s"), + name, + location=location, + ) + elif is_args or is_kwargs and not (is_args and is_kwargs): name_ = args if is_args else kwargs other = "*args" if not is_args else "**kwargs" logger.warning( @@ -896,7 +910,7 @@ class NumpyDocstring(GoogleDocstring): name_, other, name, - location=None, + location=location, ) elif is_args and is_kwargs and rest: logger.warning( @@ -904,7 +918,7 @@ class NumpyDocstring(GoogleDocstring): args, kwargs, name, - location=None, + location=location, ) return ", ".join([func(args), func(kwargs)]) -- cgit v1.2.1 From e37bfaea83bf743355ffa16413695930226cfe92 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 12 Jul 2020 01:37:20 +0200 Subject: add a method to get the current docstring's location --- sphinx/ext/napoleon/docstring.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 1eb0a35cb..ac8d05bc9 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -879,6 +879,12 @@ class NumpyDocstring(GoogleDocstring): self._directive_sections = ['.. index::'] super().__init__(docstring, config, app, what, name, obj, options) + def _get_location(self): + filepath = self._obj.__code__.co_filename + name = self._name + + return "{}: docstring of {}:".format(filepath, name) + def _escape_args_and_kwargs(self, name: str) -> str: func = super()._escape_args_and_kwargs @@ -894,8 +900,7 @@ class NumpyDocstring(GoogleDocstring): is_args = check_args(args) is_kwargs = check_kwargs(kwargs) - location_name = "docstring of {}".format(self._name) - location = ":".join([self._obj.__code__.co_filename, location_name, ""]) + location = self._get_location() if check_args(kwargs) or check_kwargs(args): logger.warning( __("wrong order of *args and **kwargs: %s"), -- cgit v1.2.1 From 0bb05031e43a8f0861be3db78e417ae4ef2ddefd Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 12 Jul 2020 02:22:03 +0200 Subject: make sure to return None if both path and name are None i.e. most likely a test --- sphinx/ext/napoleon/docstring.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index ac8d05bc9..f34912c38 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -880,9 +880,12 @@ class NumpyDocstring(GoogleDocstring): super().__init__(docstring, config, app, what, name, obj, options) def _get_location(self): - filepath = self._obj.__code__.co_filename + filepath = self._obj.__code__.co_filename if self._obj is not None else None name = self._name + if filepath is None and name is None: + return None + return "{}: docstring of {}:".format(filepath, name) def _escape_args_and_kwargs(self, name: str) -> str: -- cgit v1.2.1 From 5f12d5b476d2f14fc6ff9f609005e36268dc8bea Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 12 Jul 2020 16:18:04 +0200 Subject: use inspect.getfile instead --- sphinx/ext/napoleon/docstring.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index f34912c38..58d86365b 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -879,8 +879,8 @@ class NumpyDocstring(GoogleDocstring): self._directive_sections = ['.. index::'] super().__init__(docstring, config, app, what, name, obj, options) - def _get_location(self): - filepath = self._obj.__code__.co_filename if self._obj is not None else None + def _get_location(self) -> str: + filepath = inspect.getfile(self._obj) if self._obj is not None else None name = self._name if filepath is None and name is None: -- cgit v1.2.1 From b66f3e143e6b10fda4d140edf13d7cfaf1144d50 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 13 Jul 2020 15:40:29 +0200 Subject: fix the conditions for warning --- sphinx/ext/napoleon/docstring.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 58d86365b..fc7a3ea95 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -904,13 +904,13 @@ class NumpyDocstring(GoogleDocstring): is_kwargs = check_kwargs(kwargs) location = self._get_location() - if check_args(kwargs) or check_kwargs(args): + if (not is_args and check_args(kwargs)) and (not is_kwargs and check_kwargs(args)): logger.warning( __("wrong order of *args and **kwargs: %s"), name, location=location, ) - elif is_args or is_kwargs and not (is_args and is_kwargs): + elif (is_args or is_kwargs) and not (is_args and is_kwargs): name_ = args if is_args else kwargs other = "*args" if not is_args else "**kwargs" logger.warning( -- cgit v1.2.1 From 467533ffe87ec0aba9a17c8a567df555d9a448f7 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 13 Jul 2020 15:49:03 +0200 Subject: add tests to make sure the warning is raised --- sphinx/ext/napoleon/docstring.py | 2 +- tests/test_ext_napoleon_docstring.py | 45 ++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index fc7a3ea95..691139a48 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -883,7 +883,7 @@ class NumpyDocstring(GoogleDocstring): filepath = inspect.getfile(self._obj) if self._obj is not None else None name = self._name - if filepath is None and name is None: + if filepath is None and not name: return None return "{}: docstring of {}:".format(filepath, name) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 879a2aaa4..e24c7ed78 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -9,11 +9,15 @@ :license: BSD, see LICENSE for details. """ +import re from collections import namedtuple +from contextlib import contextmanager from inspect import cleandoc from textwrap import dedent from unittest import TestCase, mock +import pytest + from sphinx.ext.napoleon import Config from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring @@ -2003,3 +2007,44 @@ Do as you please :kwtype gotham_is_yours: None """ self.assertEqual(expected, actual) + + +@contextmanager +def warns(warning, match): + match_re = re.compile(match) + try: + yield warning + finally: + raw_warnings = warning.getvalue() + warnings = [w for w in raw_warnings.split("\n") if w.strip()] + + assert len(warnings) == 1 and all(match_re.match(w) for w in warnings) + + +class TestNumpyDocstring: + @pytest.mark.parametrize( + ["spec", "pattern"], + ( + pytest.param("*args, *kwargs", ".+: can only combine parameters of form", id="two args"), + pytest.param("**args, **kwargs", ".+: can only combine parameters of form", id="two kwargs"), + pytest.param( + "*args, **kwargs, other_parameter", + ".+: cannot combine .+ and .+ with more parameters", + id="more parameters", + ), + pytest.param("**kwargs, *args", r".+: wrong order of .+ and .+", id="swapped parameters"), + ) + ) + def test_invalid_combined_args_and_kwargs(self, spec, pattern, app, warning): + docstring = dedent( + """\ + Parameters + ---------- + {} + variable args list and arbitrary keyword arguments + """ + ).format(spec) + config = Config() + + with warns(warning, match=pattern): + str(NumpyDocstring(docstring, config, app, "method")) -- cgit v1.2.1 From 2a3f6e4d7009cc6c6105e45ae07c135e9455ecb9 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 2 Aug 2020 19:28:01 +0200 Subject: don't try to split along ', ' --- sphinx/util/docfields.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py index c07bc7f66..55c00c2ec 100644 --- a/sphinx/util/docfields.py +++ b/sphinx/util/docfields.py @@ -322,6 +322,8 @@ class DocFieldTransformer: if typedesc.is_typed: try: argtype, argname = fieldarg.split(None, 1) + if argtype.endswith(","): + raise ValueError except ValueError: pass else: -- cgit v1.2.1 From fe4a158caf4d7d15d942583397a4b7ad5e84c0c2 Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Mon, 3 Aug 2020 19:30:38 +0100 Subject: Fix typos in the documentation --- doc/man/sphinx-quickstart.rst | 2 +- doc/templating.rst | 2 +- doc/usage/advanced/intl.rst | 4 ++-- doc/usage/configuration.rst | 2 +- doc/usage/restructuredtext/directives.rst | 8 ++++---- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst index 7da16ed1e..2407e3be7 100644 --- a/doc/man/sphinx-quickstart.rst +++ b/doc/man/sphinx-quickstart.rst @@ -20,7 +20,7 @@ Options .. option:: -q, --quiet - Quiet mode that will skip interactive wizard to specify options. + Quiet mode that skips the interactive wizard for specifying options. This option requires `-p`, `-a` and `-v` options. .. option:: -h, --help, --version diff --git a/doc/templating.rst b/doc/templating.rst index 0e3815c29..548f8b8d9 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -7,7 +7,7 @@ Templating ========== Sphinx uses the `Jinja `_ templating engine for its HTML -templates. Jinja is a text-based engine, and inspired by Django templates, so +templates. Jinja is a text-based engine, inspired by Django templates, so anyone having used Django will already be familiar with it. It also has excellent documentation for those who need to make themselves familiar with it. diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index fb4f289b4..67d5e10e5 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -6,8 +6,8 @@ Internationalization .. versionadded:: 1.1 Complementary to translations provided for Sphinx-generated messages such as -navigation bars, Sphinx provides mechanisms facilitating *document* translations -in itself. See the :ref:`intl-options` for details on configuration. +navigation bars, Sphinx provides mechanisms facilitating the translation of +*documents*. See the :ref:`intl-options` for details on configuration. .. figure:: /_static/translation.* :width: 100% diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 550b26e2d..add78326b 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -918,7 +918,7 @@ that use Sphinx's HTMLWriter class. .. confval:: html_short_title - A shorter "title" for the HTML docs. This is used in for links in the + A shorter "title" for the HTML docs. This is used for links in the header and in the HTML Help docs. If not given, it defaults to the value of :confval:`html_title`. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index fcdbc3f16..e94106148 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -114,9 +114,9 @@ tables of contents. The ``toctree`` directive is the central element. **Additional options** - You can use ``caption`` option to provide a toctree caption and you can use - ``name`` option to provide implicit target name that can be referenced by - using :rst:role:`ref`:: + You can use the ``caption`` option to provide a toctree caption and you can + use the ``name`` option to provide an implicit target name that can be + referenced by using :rst:role:`ref`:: .. toctree:: :caption: Table of Contents @@ -246,7 +246,7 @@ The special document names (and pages generated for them) are: * every name beginning with ``_`` - Though only few such names are currently used by Sphinx, you should not + Though few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using ``_`` as a prefix for a custom template directory is fine.) -- cgit v1.2.1 From 9bac86a2fcbc8d11d3a1c395067cfd8404561051 Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Mon, 3 Aug 2020 19:30:38 +0100 Subject: Fix typo sphinx-buid in internationalization figure --- doc/_static/translation.png | Bin 20730 -> 16371 bytes doc/_static/translation.puml | 2 +- doc/_static/translation.svg | 25 +++++++++++++++++++------ 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/doc/_static/translation.png b/doc/_static/translation.png index aa5c5f018..002b3d1f3 100644 Binary files a/doc/_static/translation.png and b/doc/_static/translation.png differ diff --git a/doc/_static/translation.puml b/doc/_static/translation.puml index 5c3a7350b..7b8fc9f59 100644 --- a/doc/_static/translation.puml +++ b/doc/_static/translation.puml @@ -12,5 +12,5 @@ SphinxProject -r-> .rst .pot -r-> .po : Pootle .po -d-> .mo : msgfmt .mo -l-> TranslatedBuild -.rst -d-> TranslatedBuild : "sphinx-buid -Dlanguage=" +.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage=" @enduml diff --git a/doc/_static/translation.svg b/doc/_static/translation.svg index 74b78a1e7..4e3ab5ab4 100644 --- a/doc/_static/translation.svg +++ b/doc/_static/translation.svg @@ -1,4 +1,18 @@ -SphinxProject.rst.pot.po.motranslatorTranslatedBuildsphinx-build gettextPootlemsgfmtsphinx-buid -Dlanguage=SphinxProject.rst.pot.po.motranslatorTranslatedBuildsphinx-build gettextPootlemsgfmtsphinx-build -Dlanguage= \ No newline at end of file -- cgit v1.2.1 From cac6d1787dff552b7d2617670fcedf815af4a75c Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 4 Aug 2020 10:43:31 +0200 Subject: preprocess even with napoleon_use_param = False --- sphinx/ext/napoleon/docstring.py | 20 +++----- tests/test_ext_napoleon_docstring.py | 96 ++++++++++++++++++------------------ 2 files changed, 54 insertions(+), 62 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 95fb1e538..fbf1632e1 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -930,16 +930,9 @@ def _convert_numpy_type_spec(_type: str, location: str = None, translations: dic for token in combined_tokens ] - # don't use the object role if it's not necessary - default_translation = ( - ":class:`%s`" - if not all(type_ == "obj" for _, type_ in types) - else "%s" - ) - converters = { "literal": lambda x: "``%s``" % x, - "obj": lambda x: convert_obj(x, translations, default_translation), + "obj": lambda x: convert_obj(x, translations, ":class:`%s`"), "control": lambda x: "*%s*" % x, "delimiter": lambda x: x, "reference": lambda x: x, @@ -1067,12 +1060,11 @@ class NumpyDocstring(GoogleDocstring): _name, _type = line, '' _name, _type = _name.strip(), _type.strip() _name = self._escape_args_and_kwargs(_name) - if self._config.napoleon_use_param: - _type = _convert_numpy_type_spec( - _type, - location=self._get_location(), - translations=self._config.napoleon_type_aliases or {}, - ) + _type = _convert_numpy_type_spec( + _type, + location=self._get_location(), + translations=self._config.napoleon_type_aliases or {}, + ) if prefer_type and not _type: _type, _name = _name, _type diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 56812d193..66ccb75ad 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -64,19 +64,19 @@ Sample namedtuple subclass Quick description of attr1 - :type: Arbitrary type + :type: :class:`Arbitrary type` .. attribute:: attr2 Quick description of attr2 - :type: Another arbitrary type + :type: :class:`Another arbitrary type` .. attribute:: attr3 Adds a newline after the type - :type: Type + :type: :class:`Type` """ self.assertEqual(expected, actual) @@ -1108,7 +1108,7 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary - :Parameters: **arg1** (*str*) -- Extended + :Parameters: **arg1** (:class:`str`) -- Extended description of arg1 """ ), ( @@ -1136,14 +1136,14 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary - :Parameters: * **arg1** (*str*) -- Extended + :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1 - * **arg2** (*int*) -- Extended + * **arg2** (:class:`int`) -- Extended description of arg2 - :Keyword Arguments: * **kwarg1** (*str*) -- Extended + :Keyword Arguments: * **kwarg1** (:class:`str`) -- Extended description of kwarg1 - * **kwarg2** (*int*) -- Extended + * **kwarg2** (:class:`int`) -- Extended description of kwarg2 """ ), ( @@ -1194,7 +1194,7 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary - :Parameters: * **arg1** (*str*) -- Extended description of arg1 + :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1 * **\\*args** -- Variable length argument list. * **\\*\\*kwargs** -- Arbitrary keyword arguments. """ @@ -1316,7 +1316,7 @@ param1 : MyClass instance config = Config(napoleon_use_param=False) actual = str(NumpyDocstring(docstring, config)) expected = """\ -:Parameters: **param1** (*MyClass instance*) +:Parameters: **param1** (:class:`MyClass instance`) """ self.assertEqual(expected, actual) @@ -1324,7 +1324,7 @@ param1 : MyClass instance actual = str(NumpyDocstring(dedent(docstring), config)) expected = """\ :param param1: -:type param1: MyClass instance +:type param1: :class:`MyClass instance` """ self.assertEqual(expected, actual) @@ -1413,7 +1413,7 @@ arg_ : type expected = """ :ivar arg_: some description -:vartype arg_: type +:vartype arg_: :class:`type` """ config = Config(napoleon_use_ivar=True) @@ -1433,7 +1433,7 @@ arg_ : type expected = """ :ivar arg\\_: some description -:vartype arg\\_: type +:vartype arg\\_: :class:`type` """ config = Config(napoleon_use_ivar=True) @@ -1801,59 +1801,59 @@ definition_after_normal_text : int expected = """One line summary. :param no_list: -:type no_list: int +:type no_list: :class:`int` :param one_bullet_empty: * -:type one_bullet_empty: int +:type one_bullet_empty: :class:`int` :param one_bullet_single_line: - first line -:type one_bullet_single_line: int +:type one_bullet_single_line: :class:`int` :param one_bullet_two_lines: + first line continued -:type one_bullet_two_lines: int +:type one_bullet_two_lines: :class:`int` :param two_bullets_single_line: - first line - second line -:type two_bullets_single_line: int +:type two_bullets_single_line: :class:`int` :param two_bullets_two_lines: * first line continued * second line continued -:type two_bullets_two_lines: int +:type two_bullets_two_lines: :class:`int` :param one_enumeration_single_line: 1. first line -:type one_enumeration_single_line: int +:type one_enumeration_single_line: :class:`int` :param one_enumeration_two_lines: 1) first line continued -:type one_enumeration_two_lines: int +:type one_enumeration_two_lines: :class:`int` :param two_enumerations_one_line: (iii) first line (iv) second line -:type two_enumerations_one_line: int +:type two_enumerations_one_line: :class:`int` :param two_enumerations_two_lines: a. first line continued b. second line continued -:type two_enumerations_two_lines: int +:type two_enumerations_two_lines: :class:`int` :param one_definition_one_line: item 1 first line -:type one_definition_one_line: int +:type one_definition_one_line: :class:`int` :param one_definition_two_lines: item 1 first line continued -:type one_definition_two_lines: int +:type one_definition_two_lines: :class:`int` :param two_definitions_one_line: item 1 first line item 2 second line -:type two_definitions_one_line: int +:type two_definitions_one_line: :class:`int` :param two_definitions_two_lines: item 1 first line @@ -1861,14 +1861,14 @@ definition_after_normal_text : int item 2 second line continued -:type two_definitions_two_lines: int +:type two_definitions_two_lines: :class:`int` :param one_definition_blank_line: item 1 first line extra first line -:type one_definition_blank_line: int +:type one_definition_blank_line: :class:`int` :param two_definitions_blank_lines: item 1 @@ -1881,12 +1881,12 @@ definition_after_normal_text : int second line extra second line -:type two_definitions_blank_lines: int +:type two_definitions_blank_lines: :class:`int` :param definition_after_normal_text: text line item 1 first line -:type definition_after_normal_text: int +:type definition_after_normal_text: :class:`int` """ config = Config(napoleon_use_param=True) actual = str(NumpyDocstring(docstring, config)) @@ -1894,60 +1894,60 @@ definition_after_normal_text : int expected = """One line summary. -:Parameters: * **no_list** (*int*) - * **one_bullet_empty** (*int*) -- +:Parameters: * **no_list** (:class:`int`) + * **one_bullet_empty** (:class:`int`) -- * - * **one_bullet_single_line** (*int*) -- + * **one_bullet_single_line** (:class:`int`) -- - first line - * **one_bullet_two_lines** (*int*) -- + * **one_bullet_two_lines** (:class:`int`) -- + first line continued - * **two_bullets_single_line** (*int*) -- + * **two_bullets_single_line** (:class:`int`) -- - first line - second line - * **two_bullets_two_lines** (*int*) -- + * **two_bullets_two_lines** (:class:`int`) -- * first line continued * second line continued - * **one_enumeration_single_line** (*int*) -- + * **one_enumeration_single_line** (:class:`int`) -- 1. first line - * **one_enumeration_two_lines** (*int*) -- + * **one_enumeration_two_lines** (:class:`int`) -- 1) first line continued - * **two_enumerations_one_line** (*int*) -- + * **two_enumerations_one_line** (:class:`int`) -- (iii) first line (iv) second line - * **two_enumerations_two_lines** (*int*) -- + * **two_enumerations_two_lines** (:class:`int`) -- a. first line continued b. second line continued - * **one_definition_one_line** (*int*) -- + * **one_definition_one_line** (:class:`int`) -- item 1 first line - * **one_definition_two_lines** (*int*) -- + * **one_definition_two_lines** (:class:`int`) -- item 1 first line continued - * **two_definitions_one_line** (*int*) -- + * **two_definitions_one_line** (:class:`int`) -- item 1 first line item 2 second line - * **two_definitions_two_lines** (*int*) -- + * **two_definitions_two_lines** (:class:`int`) -- item 1 first line @@ -1955,14 +1955,14 @@ definition_after_normal_text : int item 2 second line continued - * **one_definition_blank_line** (*int*) -- + * **one_definition_blank_line** (:class:`int`) -- item 1 first line extra first line - * **two_definitions_blank_lines** (*int*) -- + * **two_definitions_blank_lines** (:class:`int`) -- item 1 @@ -1975,7 +1975,7 @@ definition_after_normal_text : int second line extra second line - * **definition_after_normal_text** (*int*) -- text line + * **definition_after_normal_text** (:class:`int`) -- text line item 1 first line @@ -2111,7 +2111,7 @@ definition_after_normal_text : int """) expected = dedent("""\ :param param1: the data to work on - :type param1: DataFrame + :type param1: :class:`DataFrame` :param param2: a parameter with different types :type param2: :class:`int` or :class:`float` or :obj:`None` :param param3: a optional mapping -- cgit v1.2.1 From cb61f0f7341bc3e52e4e3f4f3b7d03d304cfac63 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 4 Aug 2020 11:39:48 +0200 Subject: document that we don't require use_param = True anymore --- sphinx/ext/napoleon/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index 6d7406ead..6cab63c9f 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -239,7 +239,7 @@ class Config: napoleon_type_aliases : :obj:`dict` (Defaults to None) Add a mapping of strings to string, translating types in numpy - style docstrings. Only works when ``napoleon_use_param = True``. + style docstrings. napoleon_custom_sections : :obj:`list` (Defaults to None) Add a list of custom sections to include, expanding the list of parsed sections. -- cgit v1.2.1 From e79cd79cd2d1e46d57fd6b941bd6348eb53bdb17 Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 14:28:32 +0200 Subject: revert the change to DocFieldTransformer --- sphinx/util/docfields.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py index 55c00c2ec..c07bc7f66 100644 --- a/sphinx/util/docfields.py +++ b/sphinx/util/docfields.py @@ -322,8 +322,6 @@ class DocFieldTransformer: if typedesc.is_typed: try: argtype, argname = fieldarg.split(None, 1) - if argtype.endswith(","): - raise ValueError except ValueError: pass else: -- cgit v1.2.1 From 059dc108bab759711acb9491dfb4162e7cce8d4c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 1 Aug 2020 14:31:42 +0900 Subject: Close #6698: doctest: Add :no-trim-doctest-flags: options To control trimming doctest flags manually, this adds new options :trim-doctest-flags: and :no-trim-doctest-flags: to doctest directives. It helps to describes doctest module itself in python doc (see #6698). --- CHANGES | 2 ++ doc/usage/extensions/doctest.rst | 21 ++++++++++++++++++--- sphinx/ext/doctest.py | 12 +++++++++++- sphinx/transforms/post_transforms/code.py | 13 ++++++------- tests/roots/test-trim_doctest_flags/index.rst | 14 +++++++++++++- tests/test_transforms_post_transforms_code.py | 19 +++++++++++++++++++ 6 files changed, 69 insertions(+), 12 deletions(-) diff --git a/CHANGES b/CHANGES index d8a3cb915..c6d998363 100644 --- a/CHANGES +++ b/CHANGES @@ -42,6 +42,8 @@ Features added * #7768: i18n: :confval:`figure_language_filename` supports ``docpath`` token * #5208: linkcheck: Support checks for local links * #5090: setuptools: Link verbosity to distutils' -v and -q option +* #6698: doctest: Add ``:trim-doctest-flags:`` and ``:no-trim-doctest-flags:`` + options to doctest, testcode and testoutput directives * #7052: add ``:noindexentry:`` to the Python, C, C++, and Javascript domains. Update the documentation to better reflect the relationship between this option and the ``:noindex:`` option. diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index 33d6cf016..0fe9b535d 100644 --- a/doc/usage/extensions/doctest.rst +++ b/doc/usage/extensions/doctest.rst @@ -67,7 +67,7 @@ a comma-separated list of group names. default set of flags is specified by the :confval:`doctest_default_flags` configuration variable. - This directive supports three options: + This directive supports five options: * ``hide``, a flag option, hides the doctest block in other builders. By default it is shown as a highlighted doctest block. @@ -102,6 +102,11 @@ a comma-separated list of group names. Supported PEP-440 operands and notations + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ```` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + Note that like with standard doctests, you have to use ```` to signal a blank line in the expected output. The ```` is removed when building presentation output (HTML, LaTeX etc.). @@ -119,11 +124,16 @@ a comma-separated list of group names. A code block for a code-output-style test. - This directive supports one option: + This directive supports three options: * ``hide``, a flag option, hides the code block in other builders. By default it is shown as a highlighted code block. + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ```` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + .. note:: Code in a ``testcode`` block is always executed all at once, no matter how @@ -149,7 +159,7 @@ a comma-separated list of group names. The corresponding output, or the exception message, for the last :rst:dir:`testcode` block. - This directive supports two options: + This directive supports four options: * ``hide``, a flag option, hides the output block in other builders. By default it is shown as a literal block without highlighting. @@ -157,6 +167,11 @@ a comma-separated list of group names. * ``options``, a string option, can be used to give doctest flags (comma-separated) just like in normal doctest blocks. + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ```` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + Example:: .. testcode:: diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index 26966016d..7cd89ad32 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -91,7 +91,7 @@ class TestDirective(SphinxDirective): # convert s to ordinary blank lines for presentation test = code code = blankline_re.sub('', code) - if doctestopt_re.search(code): + if doctestopt_re.search(code) and 'no-trim-doctest-flags' not in self.options: if not test: test = code code = doctestopt_re.sub('', code) @@ -151,6 +151,10 @@ class TestDirective(SphinxDirective): line=self.lineno) if 'skipif' in self.options: node['skipif'] = self.options['skipif'] + if 'trim-doctest-flags' in self.options: + node['trim_flags'] = True + elif 'no-trim-doctest-flags' in self.options: + node['trim_flags'] = False return [node] @@ -165,26 +169,32 @@ class TestcleanupDirective(TestDirective): class DoctestDirective(TestDirective): option_spec = { 'hide': directives.flag, + 'no-trim-doctest-flags': directives.flag, 'options': directives.unchanged, 'pyversion': directives.unchanged_required, 'skipif': directives.unchanged_required, + 'trim-doctest-flags': directives.flag, } class TestcodeDirective(TestDirective): option_spec = { 'hide': directives.flag, + 'no-trim-doctest-flags': directives.flag, 'pyversion': directives.unchanged_required, 'skipif': directives.unchanged_required, + 'trim-doctest-flags': directives.flag, } class TestoutputDirective(TestDirective): option_spec = { 'hide': directives.flag, + 'no-trim-doctest-flags': directives.flag, 'options': directives.unchanged, 'pyversion': directives.unchanged_required, 'skipif': directives.unchanged_required, + 'trim-doctest-flags': directives.flag, } diff --git a/sphinx/transforms/post_transforms/code.py b/sphinx/transforms/post_transforms/code.py index add35647b..2012d6e11 100644 --- a/sphinx/transforms/post_transforms/code.py +++ b/sphinx/transforms/post_transforms/code.py @@ -9,10 +9,10 @@ """ import sys -from typing import Any, Dict, List, NamedTuple, Union +from typing import Any, Dict, List, NamedTuple from docutils import nodes -from docutils.nodes import Node +from docutils.nodes import Node, TextElement from pygments.lexers import PythonConsoleLexer, guess_lexer from sphinx import addnodes @@ -93,9 +93,6 @@ class TrimDoctestFlagsTransform(SphinxTransform): default_priority = HighlightLanguageTransform.default_priority + 1 def apply(self, **kwargs: Any) -> None: - if not self.config.trim_doctest_flags: - return - for lbnode in self.document.traverse(nodes.literal_block): # type: nodes.literal_block if self.is_pyconsole(lbnode): self.strip_doctest_flags(lbnode) @@ -103,8 +100,10 @@ class TrimDoctestFlagsTransform(SphinxTransform): for dbnode in self.document.traverse(nodes.doctest_block): # type: nodes.doctest_block self.strip_doctest_flags(dbnode) - @staticmethod - def strip_doctest_flags(node: Union[nodes.literal_block, nodes.doctest_block]) -> None: + def strip_doctest_flags(self, node: TextElement) -> None: + if not node.get('trim_flags', self.config.trim_doctest_flags): + return + source = node.rawsource source = doctest.blankline_re.sub('', source) source = doctest.doctestopt_re.sub('', source) diff --git a/tests/roots/test-trim_doctest_flags/index.rst b/tests/roots/test-trim_doctest_flags/index.rst index 63ce234cd..d63251a5a 100644 --- a/tests/roots/test-trim_doctest_flags/index.rst +++ b/tests/roots/test-trim_doctest_flags/index.rst @@ -22,7 +22,19 @@ test-trim_doctest_flags >>> datetime.date.now() # doctest: +QUX datetime.date(2008, 1, 1) -.. doctest_block:: +.. doctest:: >>> datetime.date.now() # doctest: +QUUX datetime.date(2008, 1, 1) + +.. doctest:: + :trim-doctest-flags: + + >>> datetime.date.now() # doctest: +CORGE + datetime.date(2008, 1, 1) + +.. doctest:: + :no-trim-doctest-flags: + + >>> datetime.date.now() # doctest: +GRAULT + datetime.date(2008, 1, 1) diff --git a/tests/test_transforms_post_transforms_code.py b/tests/test_transforms_post_transforms_code.py index 880f4711b..2e5da05ae 100644 --- a/tests/test_transforms_post_transforms_code.py +++ b/tests/test_transforms_post_transforms_code.py @@ -19,6 +19,23 @@ def test_trim_doctest_flags_html(app, status, warning): assert 'BAZ' not in result assert 'QUX' not in result assert 'QUUX' not in result + assert 'CORGE' not in result + assert 'GRAULT' in result + + +@pytest.mark.sphinx('html', testroot='trim_doctest_flags', + confoverrides={'trim_doctest_flags': False}) +def test_trim_doctest_flags_disabled(app, status, warning): + app.build() + + result = (app.outdir / 'index.html').read_text() + assert 'FOO' in result + assert 'BAR' in result + assert 'BAZ' in result + assert 'QUX' in result + assert 'QUUX' not in result + assert 'CORGE' not in result + assert 'GRAULT' in result @pytest.mark.sphinx('latex', testroot='trim_doctest_flags') @@ -31,3 +48,5 @@ def test_trim_doctest_flags_latex(app, status, warning): assert 'BAZ' not in result assert 'QUX' not in result assert 'QUUX' not in result + assert 'CORGE' not in result + assert 'GRAULT' in result -- cgit v1.2.1 From 849d3c18a7498fd72faa29064a0c813ed457a6af Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 19:22:43 +0200 Subject: remove the syntax checks from the escape method and update the tests --- sphinx/ext/napoleon/docstring.py | 42 +++--------------------------------- tests/test_ext_napoleon_docstring.py | 31 ++++++++------------------ 2 files changed, 12 insertions(+), 61 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 2e0acd867..df1782934 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -1090,45 +1090,9 @@ class NumpyDocstring(GoogleDocstring): func = super()._escape_args_and_kwargs if ", " in name: - args, kwargs, *rest = name.split(", ") - - def check_args(s): - return s[:1] == "*" and len([c for c in s if c == "*"]) == 1 - - def check_kwargs(s): - return s[:2] == "**" and len([c for c in s if c == "*"]) == 2 - - is_args = check_args(args) - is_kwargs = check_kwargs(kwargs) - - location = self._get_location() - if (not is_args and check_args(kwargs)) and (not is_kwargs and check_kwargs(args)): - logger.warning( - __("wrong order of *args and **kwargs: %s"), - name, - location=location, - ) - elif (is_args or is_kwargs) and not (is_args and is_kwargs): - name_ = args if is_args else kwargs - other = "*args" if not is_args else "**kwargs" - logger.warning( - __("can only combine parameters of form %s with %s: %s"), - name_, - other, - name, - location=location, - ) - elif is_args and is_kwargs and rest: - logger.warning( - __("cannot combine %s and %s with more parameters: %s"), - args, - kwargs, - name, - location=location, - ) - return ", ".join([func(args), func(kwargs)]) - - return func(name) + return ", ".join(func(param) for param in name.split(", ")) + else: + return func(name) def _consume_field(self, parse_type: bool = True, prefer_type: bool = False ) -> Tuple[str, str, List[str]]: diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 6421e5fa2..23935925b 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -2238,28 +2238,15 @@ class TestNumpyDocstring: _token_type(token) @pytest.mark.parametrize( - ["spec", "pattern"], + ("name", "expected"), ( - pytest.param("*args, *kwargs", ".+: can only combine parameters of form", id="two args"), - pytest.param("**args, **kwargs", ".+: can only combine parameters of form", id="two kwargs"), - pytest.param( - "*args, **kwargs, other_parameter", - ".+: cannot combine .+ and .+ with more parameters", - id="more parameters", - ), - pytest.param("**kwargs, *args", r".+: wrong order of .+ and .+", id="swapped parameters"), - ) + ("x, y, z", "x, y, z"), + ("*args, **kwargs", r"\*args, \*\*kwargs"), + ("*x, **y", r"\*x, \*\*y"), + ), ) - def test_invalid_combined_args_and_kwargs(self, spec, pattern, app, warning): - docstring = dedent( - """\ - Parameters - ---------- - {} - variable args list and arbitrary keyword arguments - """ - ).format(spec) - config = Config() + def test_escape_args_and_kwargs(self, name, expected): + numpy_docstring = NumpyDocstring("") + actual = numpy_docstring._escape_args_and_kwargs(name) - with warns(warning, match=pattern): - str(NumpyDocstring(docstring, config, app, "method")) + assert actual == expected -- cgit v1.2.1 From 71e9a15ccfcd654722fc4290a8dc4493b94113d8 Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Wed, 5 Aug 2020 20:05:49 +0100 Subject: Don't copy graphviz.css when building man pages _static/graphviz.css is being created alongside the man pages. --- sphinx/ext/graphviz.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index 4a8dd0a4d..d97a7505e 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -385,7 +385,7 @@ def man_visit_graphviz(self: ManualPageTranslator, node: graphviz) -> None: def on_build_finished(app: Sphinx, exc: Exception) -> None: - if exc is None: + if exc is None and app.builder.format == 'html': src = path.join(sphinx.package_dir, 'templates', 'graphviz', 'graphviz.css') dst = path.join(app.outdir, '_static') copy_asset(src, dst) -- cgit v1.2.1 From 9c55630018f0d1e36cd0e3d4d9678185f7ad2775 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 6 Aug 2020 10:57:43 +0900 Subject: Update CHANGES for PR #8048 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index c6d998363..fd87b3564 100644 --- a/CHANGES +++ b/CHANGES @@ -94,6 +94,7 @@ Bugs fixed * #7993: texinfo: a warning not supporting desc_signature_line node is shown * #7869: :rst:role:`abbr` role without an explanation will show the explanation from the previous abbr role +* #8048: graphviz: graphviz.css was copied on building non-HTML document * C and C++, removed ``noindex`` directive option as it did nothing. * #7619: Duplicated node IDs are generated if node has multiple IDs -- cgit v1.2.1 From e4e9a0f4be3e9bdc82197c2fa577eec238032c39 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 6 Aug 2020 11:01:52 +0900 Subject: Update CHANGES for PR #7799 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index fd87b3564..16e103ec7 100644 --- a/CHANGES +++ b/CHANGES @@ -77,6 +77,7 @@ Bugs fixed * #7940: apidoc: An extra newline is generated at the end of the rst file if a module has submodules * #4258: napoleon: decorated special methods are not shown +* #7799: napoleon: parameters are not escaped for combined params in numpydoc * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links * #7846: html theme: XML-invalid files were generated * #7894: gettext: Wrong source info is shown when using rst_epilog -- cgit v1.2.1 From db9375363c11c31ef3e905134c5c50f125825a8d Mon Sep 17 00:00:00 2001 From: Matt from Documatt Date: Fri, 7 Aug 2020 14:46:19 +0200 Subject: Add link to third party themes on GitLab GitLab, alternative to GitHub, also contains a lot of beautiful open source themes. --- doc/usage/theming.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index e5362b9f0..fb06e8741 100644 --- a/doc/usage/theming.rst +++ b/doc/usage/theming.rst @@ -348,7 +348,7 @@ Third Party Themes There are many third-party themes available. Some of these are general use, while others are specific to an individual project. A section of third-party -themes is listed below. Many more can be found on PyPI__, GitHub__ and +themes is listed below. Many more can be found on PyPI__, GitHub__, GitLab__ and sphinx-themes.org__. .. cssclass:: clear @@ -367,4 +367,5 @@ sphinx-themes.org__. .. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme .. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type= +.. __: https://gitlab.com/explore?name=sphinx+theme .. __: https://sphinx-themes.org/ -- cgit v1.2.1 From e188d56ed1248dead58f3f8018c0e9a3f99193f7 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 7 Aug 2020 23:39:39 +0900 Subject: Update CHANGES for PR #8049 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 16e103ec7..235e34852 100644 --- a/CHANGES +++ b/CHANGES @@ -32,6 +32,8 @@ Features added * #7888: napoleon: Add aliases Warn and Raise. * #7690: napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via :confval:`napoleon_type_aliases` +* #8049: napoleon: Create a hyperlink for each the type of parameter when + :confval:`napoleon_use_params` is False * C, added :rst:dir:`c:alias` directive for inserting copies of existing declarations. * #7745: html: inventory is broken if the docname contains a space -- cgit v1.2.1 From 99e65a59be8627b0e06786e082fae3d53b2340d0 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 7 Aug 2020 23:44:30 +0900 Subject: napoleon: Fix a broken test (refs: #8049) Fix a testcase that added just before #8049 merged. --- tests/test_ext_napoleon_docstring.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index bf3c878a8..2f1e559b3 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -1230,7 +1230,7 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary - :Parameters: * **arg1** (*str*) -- Extended description of arg1 + :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1 * **\\*args, \\*\\*kwargs** -- Variable length argument list and arbitrary keyword arguments. """ ), ( -- cgit v1.2.1