From fc2ca413ece79c083d52a86df982b33e61847327 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 12 Sep 2021 18:54:36 +0900 Subject: [PATCH 1/4] refactor: Use logger.warning() instead of reporter.warning() --- sphinx/directives/other.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index e131fe82053..78890b14c9a 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -19,7 +19,7 @@ from sphinx import addnodes from sphinx.domains.changeset import VersionChange # NOQA # for compatibility from sphinx.locale import _ -from sphinx.util import docname_join, url_re +from sphinx.util import docname_join, logging, url_re from sphinx.util.docutils import SphinxDirective from sphinx.util.matching import Matcher, patfilter from sphinx.util.nodes import explicit_title_re @@ -30,6 +30,7 @@ glob_re = re.compile(r'.*[*?\[].*') +logger = logging.getLogger(__name__) def int_or_nothing(argument: str) -> int: @@ -106,9 +107,8 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: toctree['entries'].append((None, docname)) toctree['includefiles'].append(docname) if not docnames: - ret.append(self.state.document.reporter.warning( - 'toctree glob pattern %r didn\'t match any documents' - % entry, line=self.lineno)) + logger.warning('toctree glob pattern %r didn\'t match any documents', + entry, location=toctree) else: if explicit: ref = explicit.group(2) @@ -132,16 +132,14 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: else: message = 'toctree contains reference to nonexisting document %r' - ret.append(self.state.document.reporter.warning(message % docname, - line=self.lineno)) + logger.warning(message, docname, location=toctree) self.env.note_reread() else: if docname in all_docnames: all_docnames.remove(docname) else: - message = 'duplicated entry found in toctree: %s' - ret.append(self.state.document.reporter.warning(message % docname, - line=self.lineno)) + logger.warning('duplicated entry found in toctree: %s', docname, + location=toctree) toctree['entries'].append((title, docname)) toctree['includefiles'].append(docname) @@ -250,8 +248,9 @@ def run(self) -> List[Node]: self.state.nested_parse(self.content, self.content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - reporter = self.state.document.reporter - return [reporter.warning('.. acks content is not a list', line=self.lineno)] + logger.warning('.. acks content is not a list', + location=(self.env.docname, self.lineno)) + return [] return [node] @@ -274,8 +273,9 @@ def run(self) -> List[Node]: self.state.nested_parse(self.content, self.content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - reporter = self.state.document.reporter - return [reporter.warning('.. hlist content is not a list', line=self.lineno)] + logger.warning('.. hlist content is not a list', + location=(self.env.docname, self.lineno)) + return [] fulllist = node.children[0] # create a hlist node where the items are distributed npercol, nmore = divmod(len(fulllist), ncolumns) From 5c4f741fffa0d698e82d31b3dd76c34982d313b5 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 12 Sep 2021 18:58:16 +0900 Subject: [PATCH 2/4] Fix i18n: messages in sphinx.directives.other are not translated --- sphinx/directives/other.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 78890b14c9a..f04526f939c 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -18,7 +18,7 @@ from sphinx import addnodes from sphinx.domains.changeset import VersionChange # NOQA # for compatibility -from sphinx.locale import _ +from sphinx.locale import _, __ from sphinx.util import docname_join, logging, url_re from sphinx.util.docutils import SphinxDirective from sphinx.util.matching import Matcher, patfilter @@ -107,7 +107,7 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: toctree['entries'].append((None, docname)) toctree['includefiles'].append(docname) if not docnames: - logger.warning('toctree glob pattern %r didn\'t match any documents', + logger.warning(__('toctree glob pattern %r didn\'t match any documents'), entry, location=toctree) else: if explicit: @@ -128,9 +128,9 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: toctree['entries'].append((title, ref)) elif docname not in self.env.found_docs: if excluded(self.env.doc2path(docname, None)): - message = 'toctree contains reference to excluded document %r' + message = __('toctree contains reference to excluded document %r') else: - message = 'toctree contains reference to nonexisting document %r' + message = __('toctree contains reference to nonexisting document %r') logger.warning(message, docname, location=toctree) self.env.note_reread() @@ -138,7 +138,7 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: if docname in all_docnames: all_docnames.remove(docname) else: - logger.warning('duplicated entry found in toctree: %s', docname, + logger.warning(__('duplicated entry found in toctree: %s'), docname, location=toctree) toctree['entries'].append((title, docname)) @@ -248,7 +248,7 @@ def run(self) -> List[Node]: self.state.nested_parse(self.content, self.content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - logger.warning('.. acks content is not a list', + logger.warning(__('.. acks content is not a list'), location=(self.env.docname, self.lineno)) return [] return [node] @@ -273,7 +273,7 @@ def run(self) -> List[Node]: self.state.nested_parse(self.content, self.content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - logger.warning('.. hlist content is not a list', + logger.warning(__('.. hlist content is not a list'), location=(self.env.docname, self.lineno)) return [] fulllist = node.children[0] From ca146ac18be3fdb9108b8d9dcb0b165ee62e56df Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 12 Sep 2021 19:18:21 +0900 Subject: [PATCH 3/4] Close #9623: Allow to suppress warnings on excluded document found in toctree --- CHANGES | 3 +++ doc/usage/configuration.rst | 1 + sphinx/directives/other.py | 3 ++- 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 9e8bc1151e7..331f14d81ab 100644 --- a/CHANGES +++ b/CHANGES @@ -13,6 +13,9 @@ Deprecated Features added -------------- +* #9623: Allow to suppress "toctree contains reference to excluded document" + warnings using :confval:`suppress_warnings` + Bugs fixed ---------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index a6607e57eb9..dba3cc83128 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -329,6 +329,7 @@ General configuration * ``ref.python`` * ``misc.highlighting_failure`` * ``toc.circular`` + * ``toc.not_readable`` * ``toc.secnum`` * ``epub.unknown_project_files`` * ``epub.duplicated_toc_entry`` diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index f04526f939c..7e5b341f00a 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -132,7 +132,8 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: else: message = __('toctree contains reference to nonexisting document %r') - logger.warning(message, docname, location=toctree) + logger.warning(message, docname, type='toc', subtype='not_readable', + location=toctree) self.env.note_reread() else: if docname in all_docnames: From 22bec4ffe43babda23a8f0a8db0c7f5b87a24a18 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 10 Nov 2021 01:43:59 +0900 Subject: [PATCH 4/4] Fix #9623: Separate warning type 'toc.not_readable' to 'toc.excluded' --- doc/usage/configuration.rst | 5 +++++ sphinx/directives/other.py | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index dba3cc83128..395708b5752 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -329,6 +329,7 @@ General configuration * ``ref.python`` * ``misc.highlighting_failure`` * ``toc.circular`` + * ``toc.excluded`` * ``toc.not_readable`` * ``toc.secnum`` * ``epub.unknown_project_files`` @@ -361,6 +362,10 @@ General configuration Added ``epub.duplicated_toc_entry`` + .. versionchanged:: 4.3 + + Added ``toc.excluded`` and ``toc.not_readable`` + .. confval:: needs_sphinx If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 7e5b341f00a..03eb6d3d241 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -129,10 +129,12 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]: elif docname not in self.env.found_docs: if excluded(self.env.doc2path(docname, None)): message = __('toctree contains reference to excluded document %r') + subtype = 'excluded' else: message = __('toctree contains reference to nonexisting document %r') + subtype = 'not_readable' - logger.warning(message, docname, type='toc', subtype='not_readable', + logger.warning(message, docname, type='toc', subtype=subtype, location=toctree) self.env.note_reread() else: