From af3bb3687cb106c18be36f0589958fab6d60687b Mon Sep 17 00:00:00 2001 From: Tiger3018 Date: Thu, 30 Jan 2025 03:22:44 +0800 Subject: [PATCH] Use warning types and sub-types in more places (#11677) Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com> --- doc/usage/configuration.rst | 15 ++++++++++++- sphinx/directives/other.py | 4 +++- sphinx/domains/index.py | 2 +- sphinx/environment/__init__.py | 5 ++++- sphinx/environment/adapters/indexentries.py | 3 ++- sphinx/environment/adapters/toctree.py | 7 ++++-- sphinx/util/i18n.py | 24 +++++++++++++++++++-- sphinx/util/nodes.py | 2 ++ tests/test_builders/test_build_warnings.py | 2 +- 9 files changed, 54 insertions(+), 10 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 32f07bc71..29201838b 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1378,13 +1378,16 @@ Options for warning control * ``duplicate_declaration.cpp`` * ``epub.duplicated_toc_entry`` * ``epub.unknown_project_files`` + * ``i18n.babel`` * ``i18n.inconsistent_references`` + * ``i18n.not_readable`` + * ``i18n.not_writeable`` * ``image.not_readable`` * ``index`` * ``misc.copy_overwrite`` * ``misc.highlighting_failure`` - * ``ref.citation`` * ``ref.any`` + * ``ref.citation`` * ``ref.doc`` * ``ref.footnote`` * ``ref.keyword`` @@ -1394,9 +1397,11 @@ Options for warning control * ``ref.ref`` * ``ref.term`` * ``toc.circular`` + * ``toc.duplicate_entry`` * ``toc.empty_glob`` * ``toc.excluded`` * ``toc.no_title`` + * ``toc.not_included`` * ``toc.not_readable`` * ``toc.secnum`` @@ -1491,6 +1496,14 @@ Options for warning control .. versionadded:: 8.2 Added ``ref.any`` + .. versionchanged:: 8.2 + + Added ``i18n.babel``, + ``i18n.not_readable``, + ``i18n.not_writeable``, + ``toc.duplicate_entry``, and + ``toc.not_included``. + Builder options =============== diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index e6ea45906..8c3d00668 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -157,7 +157,7 @@ class TocTree(SphinxDirective): subtype = 'not_readable' logger.warning( - msg, docname, type='toc', subtype=subtype, location=toctree + msg, docname, location=toctree, type='toc', subtype=subtype ) self.env.note_reread() continue @@ -169,6 +169,8 @@ class TocTree(SphinxDirective): __('duplicated entry found in toctree: %s'), docname, location=toctree, + type='toc', + subtype='duplicate_entry', ) toctree['entries'].append((title, docname)) diff --git a/sphinx/domains/index.py b/sphinx/domains/index.py index f82901292..09a18d018 100644 --- a/sphinx/domains/index.py +++ b/sphinx/domains/index.py @@ -54,7 +54,7 @@ class IndexDomain(Domain): for entry_type, value, _target_id, _main, _category_key in node_entries: split_index_msg(entry_type, value) except ValueError as exc: - logger.warning(str(exc), location=node) + logger.warning(str(exc), location=node, type='index') node.parent.remove(node) else: for entry in node_entries: diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index 8397fdf29..1d8253350 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -796,7 +796,10 @@ class BuildEnvironment: if 'orphan' in self.metadata[docname]: continue logger.warning( - __("document isn't included in any toctree"), location=docname + __("document isn't included in any toctree"), + location=docname, + type='toc', + subtype='not_included', ) # Call _check_toc_parents here rather than in _get_toctree_ancestors() # because that method is called multiple times per document and would diff --git a/sphinx/environment/adapters/indexentries.py b/sphinx/environment/adapters/indexentries.py index ac5c10776..c19628515 100644 --- a/sphinx/environment/adapters/indexentries.py +++ b/sphinx/environment/adapters/indexentries.py @@ -141,9 +141,10 @@ class IndexEntries: __('unknown index entry type %r'), entry_type, location=docname, + type='index', ) except ValueError as err: - logger.warning(str(err), location=docname) + logger.warning(str(err), location=docname, type='index') for targets, sub_items, _category_key in new.values(): targets.sort(key=_key_func_0) diff --git a/sphinx/environment/adapters/toctree.py b/sphinx/environment/adapters/toctree.py index bb3e7b343..b7db02220 100644 --- a/sphinx/environment/adapters/toctree.py +++ b/sphinx/environment/adapters/toctree.py @@ -358,12 +358,15 @@ def _toctree_entry( ref_path = str(env.doc2path(ref, False)) if excluded(ref_path): message = __('toctree contains reference to excluded document %r') + subtype = 'excluded' elif not included(ref_path): message = __('toctree contains reference to non-included document %r') + subtype = 'not_included' else: - message = __('toctree contains reference to nonexisting document %r') + message = __('toctree contains reference to non-existing document %r') + subtype = 'not_readable' - logger.warning(message, ref, location=toctreenode) + logger.warning(message, ref, location=toctreenode, type='toc', subtype=subtype) raise return toc, refdoc diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py index ae7cf2fd7..e4d86c08d 100644 --- a/sphinx/util/i18n.py +++ b/sphinx/util/i18n.py @@ -100,14 +100,26 @@ class CatalogInfo: try: po = read_po(file_po, locale) except Exception as exc: - logger.warning(__('reading error: %s, %s'), self.po_path, exc) + logger.warning( + __('reading error: %s, %s'), + self.po_path, + exc, + type='i18n', + subtype='not_readable', + ) return with open(self.mo_path, 'wb') as file_mo: try: write_mo(file_mo, po, use_fuzzy) except Exception as exc: - logger.warning(__('writing error: %s, %s'), self.mo_path, exc) + logger.warning( + __('writing error: %s, %s'), + self.mo_path, + exc, + type='i18n', + subtype='not_writeable', + ) class CatalogRepository: @@ -224,6 +236,12 @@ def babel_format_date( return formatter(date, format, locale=locale) except (ValueError, babel.core.UnknownLocaleError): # fallback to English + logger.warning( + __('Invalid Babel locale: %r.'), + locale, + type='i18n', + subtype='babel', + ) return formatter(date, format, locale='en') except AttributeError: logger.warning( @@ -232,6 +250,8 @@ def babel_format_date( 'if you want to output it directly: %s' ), format, + type='i18n', + subtype='babel', ) return format diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py index aaa10e09d..d17e876ba 100644 --- a/sphinx/util/nodes.py +++ b/sphinx/util/nodes.py @@ -485,6 +485,8 @@ def inline_all_toctrees( __('toctree contains ref to nonexisting file %r'), includefile, location=docname, + type='toc', + subtype='not_readable', ) else: sof = addnodes.start_of_file(docname=includefile) diff --git a/tests/test_builders/test_build_warnings.py b/tests/test_builders/test_build_warnings.py index 7178abb64..caaadabbc 100644 --- a/tests/test_builders/test_build_warnings.py +++ b/tests/test_builders/test_build_warnings.py @@ -15,7 +15,7 @@ ENV_WARNINGS = """\ 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 \\[docutils\\] -{root}/index.rst:\\d+: WARNING: invalid single index entry '' +{root}/index.rst:\\d+: WARNING: invalid single index entry '' \\[index\\] {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 \