Turn show_warning_types on by default (sphinx-doc#12597)

Co-authored-by: Adam Turner <[email protected]>

Author: chrisjsewell

CHANGES.rst

@@ -57,6 +57,9 @@ Incompatible changes
   * :confval:`linkcheck_report_timeouts_as_broken` is now ``False`` by default.
 
   Patch by James Addison.
+* #12597: Change the default of :confval:`show_warning_types`
+  from ``False`` to ``True``.
+  Patch by Chris Sewell.
 
 Deprecated
 ----------

doc/usage/configuration.rst

@@ -1331,14 +1331,16 @@ Options for warning control
 
 .. confval:: show_warning_types
    :type: :code-py:`bool`
-   :default: :code-py:`False`
+   :default: :code-py:`True`
 
    Add the type of each warning as a suffix to the warning message.
    For example, ``WARNING: [...] [index]`` or ``WARNING: [...] [toc.circular]``.
    This setting can be useful for determining which warnings types to include
    in a :confval:`suppress_warnings` list.
 
    .. versionadded:: 7.3.0
+   .. versionchanged:: 8.0.0
+      The default is now :code-py:`True`.
 
 .. confval:: suppress_warnings
    :type: :code-py:`Sequence[str]`

sphinx/config.py

@@ -244,7 +244,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', frozenset((bool,))),
+        'show_warning_types': _Opt(True, 'env', frozenset((bool,))),
         'modindex_common_prefix': _Opt([], 'html', ()),
         'rst_epilog': _Opt(None, 'env', frozenset((str,))),
         'rst_prolog': _Opt(None, 'env', frozenset((str,))),

tests/test_builders/test_build_warnings.py

@@ -8,33 +8,33 @@
 
 ENV_WARNINGS = """\
 {root}/autodoc_fodder.py:docstring of autodoc_fodder.MarkupError:\\d+: \
-WARNING: Explicit markup ends without a blank line; unexpected unindent.
+WARNING: Explicit markup ends without a blank line; unexpected unindent. \\[docutils\\]
 {root}/index.rst:\\d+: WARNING: Encoding 'utf-8-sig' used for reading included \
-file '{root}/wrongenc.inc' seems to be wrong, try giving an :encoding: option
+file '{root}/wrongenc.inc' seems to be wrong, try giving an :encoding: option \\[docutils\\]
 {root}/index.rst:\\d+: WARNING: invalid single index entry ''
-{root}/index.rst:\\d+: WARNING: image file not readable: foo.png
-{root}/index.rst:\\d+: WARNING: download file not readable: {root}/nonexisting.png
+{root}/index.rst:\\d+: WARNING: image file not readable: foo.png \\[image.not_readable\\]
+{root}/index.rst:\\d+: WARNING: download file not readable: {root}/nonexisting.png \\[download.not_readable\\]
 {root}/undecodable.rst:\\d+: WARNING: undecodable source characters, replacing \
 with "\\?": b?'here: >>>(\\\\|/)xbb<<<((\\\\|/)r)?'
 """
 
 HTML_WARNINGS = ENV_WARNINGS + """\
-{root}/index.rst:\\d+: WARNING: unknown option: '&option'
-{root}/index.rst:\\d+: WARNING: citation not found: missing
+{root}/index.rst:\\d+: WARNING: unknown option: '&option' \\[ref.option\\]
+{root}/index.rst:\\d+: WARNING: citation not found: missing \\[ref.ref\\]
 {root}/index.rst:\\d+: WARNING: a suitable image for html builder not found: foo.\\*
-{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode.
+{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode. \\[misc.highlighting_failure\\]
 """
 
 LATEX_WARNINGS = ENV_WARNINGS + """\
-{root}/index.rst:\\d+: WARNING: unknown option: '&option'
-{root}/index.rst:\\d+: WARNING: citation not found: missing
+{root}/index.rst:\\d+: WARNING: unknown option: '&option' \\[ref.option\\]
+{root}/index.rst:\\d+: WARNING: citation not found: missing \\[ref.ref\\]
 {root}/index.rst:\\d+: WARNING: a suitable image for latex builder not found: foo.\\*
-{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode.
+{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode. \\[misc.highlighting_failure\\]
 """
 
 TEXINFO_WARNINGS = ENV_WARNINGS + """\
-{root}/index.rst:\\d+: WARNING: unknown option: '&option'
-{root}/index.rst:\\d+: WARNING: citation not found: missing
+{root}/index.rst:\\d+: WARNING: unknown option: '&option' \\[ref.option\\]
+{root}/index.rst:\\d+: WARNING: citation not found: missing \\[ref.ref\\]
 {root}/index.rst:\\d+: WARNING: a suitable image for texinfo builder not found: foo.\\*
 {root}/index.rst:\\d+: WARNING: a suitable image for texinfo builder not found: \
 \\['application/pdf', 'image/svg\\+xml'\\] \\(svgimg.\\*\\)

tests/test_extensions/test_ext_intersphinx.py

@@ -575,14 +575,14 @@ def test_intersphinx_role(app, warning):
     warnings = strip_colors(warning.getvalue()).splitlines()
     index_path = app.srcdir / 'index.rst'
     assert warnings == [
-        f"{index_path}:21: WARNING: role for external cross-reference not found in domain 'py': 'nope'",
-        f"{index_path}:28: WARNING: role for external cross-reference not found in domains 'cpp', 'std': 'nope'",
-        f"{index_path}:39: WARNING: inventory for external cross-reference not found: 'invNope'",
-        f"{index_path}:44: WARNING: role for external cross-reference not found in domain 'c': 'function' (perhaps you meant one of: 'func', 'identifier', 'type')",
-        f"{index_path}:45: WARNING: role for external cross-reference not found in domains 'cpp', 'std': 'function' (perhaps you meant one of: 'cpp:func', 'cpp:identifier', 'cpp:type')",
-        f'{index_path}:9: WARNING: external py:mod reference target not found: module3',
-        f'{index_path}:14: WARNING: external py:mod reference target not found: module10',
-        f'{index_path}:19: WARNING: external py:meth reference target not found: inv:Foo.bar',
+        f"{index_path}:21: WARNING: role for external cross-reference not found in domain 'py': 'nope' [intersphinx.external]",
+        f"{index_path}:28: WARNING: role for external cross-reference not found in domains 'cpp', 'std': 'nope' [intersphinx.external]",
+        f"{index_path}:39: WARNING: inventory for external cross-reference not found: 'invNope' [intersphinx.external]",
+        f"{index_path}:44: WARNING: role for external cross-reference not found in domain 'c': 'function' (perhaps you meant one of: 'func', 'identifier', 'type') [intersphinx.external]",
+        f"{index_path}:45: WARNING: role for external cross-reference not found in domains 'cpp', 'std': 'function' (perhaps you meant one of: 'cpp:func', 'cpp:identifier', 'cpp:type') [intersphinx.external]",
+        f'{index_path}:9: WARNING: external py:mod reference target not found: module3 [ref.mod]',
+        f'{index_path}:14: WARNING: external py:mod reference target not found: module10 [ref.mod]',
+        f'{index_path}:19: WARNING: external py:meth reference target not found: inv:Foo.bar [ref.meth]',
     ]
 
     html = '<a class="reference external" href="https://example.org/{}" title="(in foo v2.0)">'

tests/test_intl/test_intl.py

@@ -96,7 +96,7 @@ def test_text_emit_warnings(app, warning):
     # test warnings in translation
     warnings = getwarning(warning)
     warning_expr = ('.*/warnings.txt:4:<translated>:1: '
-                    'WARNING: Inline literal start-string without end-string.\n')
+                    'WARNING: Inline literal start-string without end-string. \\[docutils\\]\n')
     assert re.search(warning_expr, warnings), f'{warning_expr!r} did not match {warnings!r}'
 
 
@@ -156,7 +156,7 @@ def test_text_inconsistency_warnings(app, warning):
     warnings = getwarning(warning)
     warning_fmt = ('.*/refs_inconsistency.txt:\\d+: '
                    'WARNING: inconsistent %(reftype)s in translated message.'
-                   ' original: %(original)s, translated: %(translated)s\n')
+                   ' original: %(original)s, translated: %(translated)s \\[i18n.inconsistent_references\\]\n')
     expected_warning_expr = (
         warning_fmt % {
             'reftype': 'footnote references',
@@ -310,7 +310,7 @@ def test_text_glossary_term_inconsistencies(app, warning):
         '.*/glossary_terms_inconsistency.txt:\\d+: '
         'WARNING: inconsistent term references in translated message.'
         " original: \\[':term:`Some term`', ':term:`Some other term`'\\],"
-        " translated: \\[':term:`SOME NEW TERM`'\\]\n")
+        " translated: \\[':term:`SOME NEW TERM`'\\] \\[i18n.inconsistent_references\\]\n")
     assert re.search(expected_warning_expr, warnings), f'{expected_warning_expr!r} did not match {warnings!r}'
     expected_warning_expr = (
         '.*/glossary_terms_inconsistency.txt:\\d+:<translated>:1: '