diff --git a/CHANGES b/CHANGES index c1479351405..421c9ecec58 100644 --- a/CHANGES +++ b/CHANGES @@ -55,6 +55,8 @@ Features added inventory specification. Specific types of cross-references can be disabled, e.g., ``std:doc`` or all cross-references in a specific domain, e.g., ``std:*``. +* #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 6725bd3e0c9..551ef5dbda6 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -329,6 +329,8 @@ General configuration * ``ref.python`` * ``misc.highlighting_failure`` * ``toc.circular`` + * ``toc.excluded`` + * ``toc.not_readable`` * ``toc.secnum`` * ``epub.unknown_project_files`` * ``epub.duplicated_toc_entry`` @@ -360,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 e131fe82053..03eb6d3d241 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -18,8 +18,8 @@ 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.locale import _, __ +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) @@ -128,20 +128,21 @@ 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') + subtype = 'excluded' else: - message = 'toctree contains reference to nonexisting document %r' + message = __('toctree contains reference to nonexisting document %r') + subtype = 'not_readable' - ret.append(self.state.document.reporter.warning(message % docname, - line=self.lineno)) + logger.warning(message, docname, type='toc', subtype=subtype, + 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 +251,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 +276,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)