Merge pull request #5715 from tk0miya/refactor_writers

Refactor writers

CHANGES

@@ -52,6 +52,9 @@ Deprecated
 * ``sphinx.util.osutil.walk()``
 * ``sphinx.util.pycompat.u``
 * ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
+* ``sphinx.writers.latex.TextTranslator._make_visit_admonition()``
+* ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
+* ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
 * template variables for LaTeX template
 
   - ``pageautorefname``

doc/extdev/index.rst

@@ -187,6 +187,21 @@ The following is a list of deprecated interfaces.
      - 3.0
      - N/A
 
+   * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
    * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
      - 2.0
      - 4.0

sphinx/writers/latex.py

@@ -1811,35 +1811,33 @@ class LaTeXTranslator(SphinxTranslator):
         # type: (nodes.admonition) -> None
         self.body.append('\\end{sphinxadmonition}\n')
 
-    def _make_visit_admonition(name):
-        # type: (unicode) -> Callable[[LaTeXTranslator, nodes.Element], None]
-        def visit_admonition(self, node):
-            # type: (nodes.Element) -> None
-            self.body.append(u'\n\\begin{sphinxadmonition}{%s}{%s:}' %
-                             (name, admonitionlabels[name]))
-        return visit_admonition
+    def _visit_named_admonition(self, node):
+        # type: (nodes.Element) -> None
+        label = admonitionlabels[node.tagname]
+        self.body.append(u'\n\\begin{sphinxadmonition}{%s}{%s:}' %
+                         (node.tagname, label))
 
     def _depart_named_admonition(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.Element) -> None
         self.body.append('\\end{sphinxadmonition}\n')
 
-    visit_attention = _make_visit_admonition('attention')
+    visit_attention = _visit_named_admonition
     depart_attention = _depart_named_admonition
-    visit_caution = _make_visit_admonition('caution')
+    visit_caution = _visit_named_admonition
     depart_caution = _depart_named_admonition
-    visit_danger = _make_visit_admonition('danger')
+    visit_danger = _visit_named_admonition
     depart_danger = _depart_named_admonition
-    visit_error = _make_visit_admonition('error')
+    visit_error = _visit_named_admonition
     depart_error = _depart_named_admonition
-    visit_hint = _make_visit_admonition('hint')
+    visit_hint = _visit_named_admonition
     depart_hint = _depart_named_admonition
-    visit_important = _make_visit_admonition('important')
+    visit_important = _visit_named_admonition
     depart_important = _depart_named_admonition
-    visit_note = _make_visit_admonition('note')
+    visit_note = _visit_named_admonition
     depart_note = _depart_named_admonition
-    visit_tip = _make_visit_admonition('tip')
+    visit_tip = _visit_named_admonition
     depart_tip = _depart_named_admonition
-    visit_warning = _make_visit_admonition('warning')
+    visit_warning = _visit_named_admonition
     depart_warning = _depart_named_admonition
 
     def visit_versionmodified(self, node):
@@ -2663,6 +2661,17 @@ class LaTeXTranslator(SphinxTranslator):
 
         return ('%s\\def%s{%s}%s\n' % (prefix, name, definition, suffix))
 
+    def _make_visit_admonition(name):
+        # type: (unicode) -> Callable[[LaTeXTranslator, nodes.Element], None]
+        warnings.warn('LaTeXTranslator._make_visit_admonition() is deprecated.',
+                      RemovedInSphinx30Warning)
+
+        def visit_admonition(self, node):
+            # type: (nodes.Element) -> None
+            self.body.append(u'\n\\begin{sphinxadmonition}{%s}{%s:}' %
+                             (name, admonitionlabels[name]))
+        return visit_admonition
+
 # Import old modules here for compatibility
 # They should be imported after `LaTeXTranslator` to avoid recursive import.
 #

sphinx/writers/texinfo.py

@@ -11,12 +11,14 @@
 
 import re
 import textwrap
+import warnings
 from os import path
 from typing import Iterable, cast
 
 from docutils import nodes, writers
 
 from sphinx import addnodes, __display_version__
+from sphinx.deprecation import RemovedInSphinx30Warning
 from sphinx.errors import ExtensionError
 from sphinx.locale import admonitionlabels, _, __
 from sphinx.util import logging
@@ -1205,36 +1207,34 @@ class TexinfoTranslator(SphinxTranslator):
             name = self.escape(node[0].astext())
         self.body.append(u'\n@cartouche\n@quotation %s ' % name)
 
+    def _visit_named_admonition(self, node):
+        # type: (nodes.Element) -> None
+        label = admonitionlabels[node.tagname]
+        self.body.append(u'\n@cartouche\n@quotation %s ' % label)
+
     def depart_admonition(self, node):
         # type: (nodes.admonition) -> None
         self.ensure_eol()
         self.body.append('@end quotation\n'
                          '@end cartouche\n')
 
-    def _make_visit_admonition(name):
-        # type: (unicode) -> Callable[[TexinfoTranslator, nodes.Node], None]
-        def visit(self, node):
-            # type: (nodes.Node) -> None
-            self.visit_admonition(node, admonitionlabels[name])
-        return visit
-
-    visit_attention = _make_visit_admonition('attention')
+    visit_attention = _visit_named_admonition
     depart_attention = depart_admonition
-    visit_caution = _make_visit_admonition('caution')
+    visit_caution = _visit_named_admonition
     depart_caution = depart_admonition
-    visit_danger = _make_visit_admonition('danger')
+    visit_danger = _visit_named_admonition
     depart_danger = depart_admonition
-    visit_error = _make_visit_admonition('error')
+    visit_error = _visit_named_admonition
     depart_error = depart_admonition
-    visit_hint = _make_visit_admonition('hint')
+    visit_hint = _visit_named_admonition
     depart_hint = depart_admonition
-    visit_important = _make_visit_admonition('important')
+    visit_important = _visit_named_admonition
     depart_important = depart_admonition
-    visit_note = _make_visit_admonition('note')
+    visit_note = _visit_named_admonition
     depart_note = depart_admonition
-    visit_tip = _make_visit_admonition('tip')
+    visit_tip = _visit_named_admonition
     depart_tip = depart_admonition
-    visit_warning = _make_visit_admonition('warning')
+    visit_warning = _visit_named_admonition
     depart_warning = depart_admonition
 
     # -- Misc
@@ -1741,3 +1741,13 @@ class TexinfoTranslator(SphinxTranslator):
         self.body.append('\n\n@example\n%s\n@end example\n\n' %
                          self.escape_arg(node.astext()))
         raise nodes.SkipNode
+
+    def _make_visit_admonition(name):
+        # type: (unicode) -> Callable[[TexinfoTranslator, nodes.Node], None]
+        warnings.warn('TexinfoTranslator._make_visit_admonition() is deprecated.',
+                      RemovedInSphinx30Warning)
+
+        def visit(self, node):
+            # type: (nodes.Node) -> None
+            self.visit_admonition(node, admonitionlabels[name])
+        return visit

sphinx/writers/text.py

@@ -12,6 +12,7 @@ import math
 import os
 import re
 import textwrap
+import warnings
 from itertools import groupby, chain
 from typing import Iterable, cast
 
@@ -19,6 +20,7 @@ from docutils import nodes, writers
 from docutils.utils import column_width
 
 from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx30Warning
 from sphinx.locale import admonitionlabels, _
 from sphinx.util.docutils import SphinxTranslator
 
@@ -1049,33 +1051,31 @@ class TextTranslator(SphinxTranslator):
         if isinstance(node.children[0], nodes.Sequential):
             self.add_text(self.nl)
 
-    def _make_depart_admonition(name):
-        # type: (unicode) -> Callable[[TextTranslator, nodes.Element], None]
-        def depart_admonition(self, node):
-            # type: (nodes.Element) -> None
-            self.end_state(first=admonitionlabels[name] + ': ')
-        return depart_admonition
+    def _depart_admonition(self, node):
+        # type: (nodes.Element) -> None
+        label = admonitionlabels[node.tagname]
+        self.end_state(first=label + ': ')
 
     visit_attention = _visit_admonition
-    depart_attention = _make_depart_admonition('attention')
+    depart_attention = _depart_admonition
     visit_caution = _visit_admonition
-    depart_caution = _make_depart_admonition('caution')
+    depart_caution = _depart_admonition
     visit_danger = _visit_admonition
-    depart_danger = _make_depart_admonition('danger')
+    depart_danger = _depart_admonition
     visit_error = _visit_admonition
-    depart_error = _make_depart_admonition('error')
+    depart_error = _depart_admonition
     visit_hint = _visit_admonition
-    depart_hint = _make_depart_admonition('hint')
+    depart_hint = _depart_admonition
     visit_important = _visit_admonition
-    depart_important = _make_depart_admonition('important')
+    depart_important = _depart_admonition
     visit_note = _visit_admonition
-    depart_note = _make_depart_admonition('note')
+    depart_note = _depart_admonition
     visit_tip = _visit_admonition
-    depart_tip = _make_depart_admonition('tip')
+    depart_tip = _depart_admonition
     visit_warning = _visit_admonition
-    depart_warning = _make_depart_admonition('warning')
+    depart_warning = _depart_admonition
     visit_seealso = _visit_admonition
-    depart_seealso = _make_depart_admonition('seealso')
+    depart_seealso = _depart_admonition
 
     def visit_versionmodified(self, node):
         # type: (addnodes.versionmodified) -> None
@@ -1370,3 +1370,13 @@ class TextTranslator(SphinxTranslator):
     def unknown_visit(self, node):
         # type: (nodes.Node) -> None
         raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
+
+    def _make_depart_admonition(name):
+        # type: (unicode) -> Callable[[TextTranslator, nodes.Element], None]
+        warnings.warn('TextTranslator._make_depart_admonition() is deprecated.',
+                      RemovedInSphinx30Warning)
+
+        def depart_admonition(self, node):
+            # type: (nodes.Element) -> None
+            self.end_state(first=admonitionlabels[name] + ': ')
+        return depart_admonition