From 75914c67c77e94b0af71fbab424ad1e18e218b97 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sun, 5 Dec 2021 15:03:57 -0500 Subject: [PATCH] drop translator-specific unknown_visit calls Removes the need for various translators from raising a `NotImplementedError` exception when missing support for a specific node type. docutils will already raise [1][2] a `NotImplementedError` exception for these cases. This help reduce the implementation inside Sphinx as well as prevents the possible undesired replication of unknown-node handling with third-party extensions [3]. In most cases, generating a warning message for an unsupported node type can be preferred. Providing an indication that a node is not supported can be easier for a user of Sphinx to understand a limitation of a builder over a generic "not implemented" exception. This commit takes the logging call which is already used by `texinfo` and applies it to the `SphinxTranslator` base class -- which any Sphinx translator implementation can use. [1]: https://repo.or.cz/docutils.git/blob/d169015ee0f412cffd69b33654d8a119d99bc0f3:/docutils/nodes.py#l2048 [2]: https://repo.or.cz/docutils.git/blob/53716a13b48128af6045139d3cd2909f61e7ed8e:/docutils/nodes.py#l1897 [3]: https://github.com/sphinx-doc/sphinx/issues/9921 Signed-off-by: James Knight --- sphinx/util/docutils.py | 5 ++++- sphinx/writers/html.py | 3 --- sphinx/writers/html5.py | 3 --- sphinx/writers/latex.py | 3 --- sphinx/writers/manpage.py | 3 --- sphinx/writers/texinfo.py | 4 ---- sphinx/writers/text.py | 3 --- 7 files changed, 4 insertions(+), 20 deletions(-) diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index c3d385306..39fa02d31 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -28,7 +28,7 @@ from docutils.utils import Reporter, unescape from packaging import version from sphinx.errors import SphinxError -from sphinx.locale import _ +from sphinx.locale import _, __ from sphinx.util import logging from sphinx.util.typing import RoleFunction @@ -496,6 +496,9 @@ class SphinxTranslator(nodes.NodeVisitor): else: super().dispatch_departure(node) + def unknown_visit(self, node: Node) -> None: + logger.warning(__('unknown node type: %r'), node, location=node) + # cache a vanilla instance of nodes.document # Used in new_document() function diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index fead4c61d..143c2ef71 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -876,9 +876,6 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator): if depart: depart(self, node) - def unknown_visit(self, node: Node) -> None: - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) - @property def permalink_text(self) -> str: warnings.warn('HTMLTranslator.permalink_text is deprecated.', diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index bba07f447..adb463662 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -811,9 +811,6 @@ class HTML5Translator(SphinxTranslator, BaseTranslator): if depart: depart(self, node) - def unknown_visit(self, node: Node) -> None: - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) - @property def permalink_text(self) -> str: warnings.warn('HTMLTranslator.permalink_text is deprecated.', diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 3f032e616..e5bd028f9 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -2079,9 +2079,6 @@ class LaTeXTranslator(SphinxTranslator): def depart_math_reference(self, node: Element) -> None: pass - def unknown_visit(self, node: Node) -> None: - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) - # FIXME: Workaround to avoid circular import # refs: https://github.com/sphinx-doc/sphinx/issues/5433 diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index da5f4c241..db8c1b1d3 100644 --- a/sphinx/writers/manpage.py +++ b/sphinx/writers/manpage.py @@ -462,6 +462,3 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): def depart_math_block(self, node: Element) -> None: self.depart_centered(node) - - def unknown_visit(self, node: Node) -> None: - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index 6df558323..539a72388 100644 --- a/sphinx/writers/texinfo.py +++ b/sphinx/writers/texinfo.py @@ -1265,10 +1265,6 @@ class TexinfoTranslator(SphinxTranslator): logger.warning(__("unimplemented node type: %r"), node, location=node) - def unknown_visit(self, node: Node) -> None: - logger.warning(__("unknown node type: %r"), node, - location=node) - def unknown_departure(self, node: Node) -> None: pass diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index ba310e072..a016f693f 100644 --- a/sphinx/writers/text.py +++ b/sphinx/writers/text.py @@ -1189,6 +1189,3 @@ class TextTranslator(SphinxTranslator): def depart_math_block(self, node: Element) -> None: self.end_state() - - def unknown_visit(self, node: Node) -> None: - raise NotImplementedError('Unknown node: ' + node.__class__.__name__)