From 847a4d5409107a85564b5fe59807c3cd18743d9a Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 18 Mar 2024 20:34:34 +0100 Subject: [PATCH 1/9] =?UTF-8?q?=E2=9C=A8=20Add=20`show=5Fwarning=5Ftypes`?= =?UTF-8?q?=20configuration=20variable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/conf.py | 1 + doc/usage/configuration.rst | 11 ++++++++--- sphinx/config.py | 1 + sphinx/util/logging.py | 20 ++++++++++++++++++++ tests/test_util/test_util_logging.py | 13 +++++++++++++ 5 files changed, 43 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 37f86232dce..2816935e6c0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -23,6 +23,7 @@ release = version show_authors = True nitpicky = True +show_warning_types = True html_theme = 'sphinx13' html_theme_path = ['_themes'] diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index c7b30d054af..db34f4316d9 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -326,11 +326,16 @@ General configuration .. versionadded:: 0.5 +.. confval:: show_warning_types + + If ``True``, the type of each warning is added as a suffix to the warning message. + The default is ``False``. + .. confval:: suppress_warnings A list of warning types to suppress arbitrary warning messages. - Sphinx supports following warning types: + Sphinx core supports following warning types: * ``app.add_node`` * ``app.add_directive`` @@ -359,11 +364,11 @@ General configuration * ``toc.not_readable`` * ``toc.secnum`` + Then extensions can also define their own warning types. + You can choose from these types. You can also give only the first component to exclude all warnings attached to it. - Now, this option should be considered *experimental*. - .. versionadded:: 1.4 .. versionchanged:: 1.5 diff --git a/sphinx/config.py b/sphinx/config.py index e90c7ebfcb8..6cf23ed1dd4 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -227,6 +227,7 @@ class Config: 'template_bridge': _Opt(None, 'html', frozenset((str,))), 'keep_warnings': _Opt(False, 'env', ()), 'suppress_warnings': _Opt([], 'env', ()), + 'show_warning_types': _Opt(False, 'env', ()), 'modindex_common_prefix': _Opt([], 'html', ()), 'rst_epilog': _Opt(None, 'env', frozenset((str,))), 'rst_prolog': _Opt(None, 'env', frozenset((str,))), diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index baff073253c..8821da2613c 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -480,6 +480,7 @@ class SphinxLogRecordTranslator(logging.Filter): * Make a instance of SphinxLogRecord * docname to path if location given + * append warning type/subtype to message if show_warning_types is True """ LogRecordClass: type[logging.LogRecord] @@ -511,6 +512,8 @@ def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore[overri return True + + class InfoLogRecordTranslator(SphinxLogRecordTranslator): """LogRecordTranslator for INFO level log records.""" @@ -522,6 +525,23 @@ class WarningLogRecordTranslator(SphinxLogRecordTranslator): LogRecordClass = SphinxWarningLogRecord + def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore[override] + super().filter(record) + + try: + show_warning_types = self.app.config.show_warning_types + except AttributeError: + # config is not initialized yet (ex. in conf.py) + show_warning_types = False + if show_warning_types: + if log_type := getattr(record, 'type', ''): + if log_subtype := getattr(record, 'subtype', ''): + record.msg += f' [{log_type}.{log_subtype}]' + else: + record.msg += f' [{log_type}]' + + return True + def get_node_location(node: Node) -> str | None: source, line = get_source_line(node) diff --git a/tests/test_util/test_util_logging.py b/tests/test_util/test_util_logging.py index 4d506a8a862..463e603b786 100644 --- a/tests/test_util/test_util_logging.py +++ b/tests/test_util/test_util_logging.py @@ -396,3 +396,16 @@ def test_get_node_location_abspath(): location = logging.get_node_location(n) assert location == absolute_filename + ':' + + +@pytest.mark.sphinx(confoverrides={'show_warning_types': True}) +def test_show_warning_types(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + logger.warning('message2') + logger.warning('message3', type='test') + logger.warning('message4', type='test', subtype='logging') + + assert 'WARNING: message2' in warning.getvalue() + assert 'WARNING: message3 [test]' in warning.getvalue() + assert 'WARNING: message4 [test.logging]' in warning.getvalue() From fc73134e89b3a024b3c2d3328b720e13f0e49730 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 18 Mar 2024 20:51:59 +0100 Subject: [PATCH 2/9] fix linting --- doc/usage/configuration.rst | 2 +- sphinx/util/logging.py | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index db34f4316d9..2db74304b74 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -364,7 +364,7 @@ General configuration * ``toc.not_readable`` * ``toc.secnum`` - Then extensions can also define their own warning types. + Then extensions can also define their own warning types. You can choose from these types. You can also give only the first component to exclude all warnings attached to it. diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 8821da2613c..63236a282aa 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -512,8 +512,6 @@ def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore[overri return True - - class InfoLogRecordTranslator(SphinxLogRecordTranslator): """LogRecordTranslator for INFO level log records.""" From d9222f18be37b878ebb99fb647e7adc32c9a9fb0 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 18 Mar 2024 20:57:54 +0100 Subject: [PATCH 3/9] Update CHANGES.rst --- CHANGES.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 8ffe9365d67..04733657806 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -22,6 +22,9 @@ Deprecated Features added -------------- +* #12131: Added :confval:`show_warning_types` configuration option. + Patch by Chris Sewell. + * #11701: HTML Search: Adopt the new ``_ element. Patch by Bénédikt Tran. From 70891f1191918ca4a35e4447ffa063a16d57fc33 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 18 Mar 2024 22:33:57 +0100 Subject: [PATCH 4/9] Update configuration.rst --- doc/usage/configuration.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 2db74304b74..23a9e534ae4 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -331,6 +331,8 @@ General configuration If ``True``, the type of each warning is added as a suffix to the warning message. The default is ``False``. + .. versionadded:: 7.3.0 + .. confval:: suppress_warnings A list of warning types to suppress arbitrary warning messages. From 14dabafcc726d74650c9303d0cfaa5bb3df15b66 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 19 Mar 2024 09:37:15 +0100 Subject: [PATCH 5/9] Update sphinx/util/logging.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- sphinx/util/logging.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 63236a282aa..cb025f2b91d 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -480,7 +480,7 @@ class SphinxLogRecordTranslator(logging.Filter): * Make a instance of SphinxLogRecord * docname to path if location given - * append warning type/subtype to message if show_warning_types is True + * append warning type/subtype to message if :confval:`show_warning_types` is ``True`` """ LogRecordClass: type[logging.LogRecord] From 9dc2b58341ea95386c4901a677a7975094b230d3 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 19 Mar 2024 09:37:55 +0100 Subject: [PATCH 6/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- sphinx/util/logging.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index cb025f2b91d..a74369862ba 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -524,7 +524,7 @@ class WarningLogRecordTranslator(SphinxLogRecordTranslator): LogRecordClass = SphinxWarningLogRecord def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore[override] - super().filter(record) + ret = super().filter(record) try: show_warning_types = self.app.config.show_warning_types @@ -538,7 +538,7 @@ def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore[overri else: record.msg += f' [{log_type}]' - return True + return ret def get_node_location(node: Node) -> str | None: From 2846793e01e053fa2357d85eca2ab9008bb3fde4 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 19 Mar 2024 09:51:29 +0100 Subject: [PATCH 7/9] Update test_util_logging.py --- tests/test_util/test_util_logging.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tests/test_util/test_util_logging.py b/tests/test_util/test_util_logging.py index 463e603b786..0926753dbcd 100644 --- a/tests/test_util/test_util_logging.py +++ b/tests/test_util/test_util_logging.py @@ -10,7 +10,7 @@ from sphinx.errors import SphinxWarning from sphinx.testing.util import strip_escseq from sphinx.util import logging, osutil -from sphinx.util.console import colorize +from sphinx.util.console import colorize, strip_colors from sphinx.util.logging import is_suppressed_warning, prefixed_warnings from sphinx.util.parallel import ParallelTasks @@ -406,6 +406,11 @@ def test_show_warning_types(app, status, warning): logger.warning('message3', type='test') logger.warning('message4', type='test', subtype='logging') - assert 'WARNING: message2' in warning.getvalue() - assert 'WARNING: message3 [test]' in warning.getvalue() - assert 'WARNING: message4 [test.logging]' in warning.getvalue() + warnings = strip_colors(warning.getvalue()).splitlines() + + assert warnings == [ + 'WARNING: message2', + 'WARNING: message3 [test]', + 'WARNING: message4 [test.logging]', + ] + From d22eaee81dd9c3b2c62c8d0a68e5c4b3679e8de2 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 19 Mar 2024 09:53:40 +0100 Subject: [PATCH 8/9] Update test_util_logging.py --- tests/test_util/test_util_logging.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tests/test_util/test_util_logging.py b/tests/test_util/test_util_logging.py index 0926753dbcd..8c621880313 100644 --- a/tests/test_util/test_util_logging.py +++ b/tests/test_util/test_util_logging.py @@ -409,8 +409,7 @@ def test_show_warning_types(app, status, warning): warnings = strip_colors(warning.getvalue()).splitlines() assert warnings == [ - 'WARNING: message2', - 'WARNING: message3 [test]', + 'WARNING: message2', + 'WARNING: message3 [test]', 'WARNING: message4 [test.logging]', ] - From 984d02150d619e9c363de087c158684fc5a0812f Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 19 Mar 2024 10:05:51 +0100 Subject: [PATCH 9/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/usage/configuration.rst | 3 ++- sphinx/config.py | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 23a9e534ae4..b5a2b84934a 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -328,7 +328,8 @@ General configuration .. confval:: show_warning_types - If ``True``, the type of each warning is added as a suffix to the warning message. + If ``True``, the type of each warning is added as a suffix to the warning message, + e.g., ``WARNING: [...] [index]`` or ``WARNING: [...] [toc.circular]``. The default is ``False``. .. versionadded:: 7.3.0 diff --git a/sphinx/config.py b/sphinx/config.py index 6cf23ed1dd4..dc8c1c11d72 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -227,7 +227,7 @@ class Config: 'template_bridge': _Opt(None, 'html', frozenset((str,))), 'keep_warnings': _Opt(False, 'env', ()), 'suppress_warnings': _Opt([], 'env', ()), - 'show_warning_types': _Opt(False, 'env', ()), + 'show_warning_types': _Opt(False, 'env', frozenset((bool,))), 'modindex_common_prefix': _Opt([], 'html', ()), 'rst_epilog': _Opt(None, 'env', frozenset((str,))), 'rst_prolog': _Opt(None, 'env', frozenset((str,))),