Reorder the arguments for translators

CHANGES

@@ -36,6 +36,8 @@ Incompatible changes
   (refs: #5772)
 * #5770: doctest: Follow :confval:`highlight_language` on highlighting doctest
   block.  As a result, they are highlighted as python3 by default.
+* The order of argument for ``HTMLTranslator``, ``HTML5Translator`` and
+  ``ManualPageTranslator`` are changed
 
 Deprecated
 ----------

sphinx/util/docutils.py

@@ -392,8 +392,8 @@ class SphinxTranslator(nodes.NodeVisitor):
               This class is strongly coupled with Sphinx.
     """
 
-    def __init__(self, builder, document):
+    def __init__(self, document, builder):
-        # type: (Builder, nodes.document) -> None
+        # type: (nodes.document, Builder) -> None
         super().__init__(document)
         self.builder = builder
         self.config = builder.config

sphinx/writers/html.py

@@ -19,7 +19,8 @@ from docutils import nodes
 from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator
 
 from sphinx import addnodes
-from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.builders import Builder
+from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 from sphinx.locale import admonitionlabels, _, __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
@@ -53,7 +54,7 @@ class HTMLWriter(Writer):
     def translate(self):
         # type: () -> None
         # sadly, this is mostly copied from parent class
-        visitor = self.builder.create_translator(self.builder, self.document)
+        visitor = self.builder.create_translator(self.document, self.builder)
         self.visitor = cast(HTMLTranslator, visitor)
         self.document.walkabout(visitor)
         self.output = self.visitor.astext()
@@ -73,9 +74,17 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
 
     builder = None  # type: StandaloneHTMLBuilder
 
-    def __init__(self, builder, document):
+    def __init__(self, *args):
-        # type: (StandaloneHTMLBuilder, nodes.document) -> None
+        # type: (Any) -> None
-        super().__init__(builder, document)
+        if isinstance(args[0], nodes.document) and isinstance(args[1], Builder):
+            document, builder = args
+        else:
+            warnings.warn('The order of arguments for HTMLTranslator has been changed. '
+                          'Please give "document" as 1st and "builder" as 2nd.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+            builder, document = args
+        super().__init__(document, builder)
+
         self.highlighter = self.builder.highlighter
         self.docnames = [self.builder.current_docname]  # for singlehtml builder
         self.manpages_url = self.config.manpages_url

sphinx/writers/html5.py

@@ -18,7 +18,8 @@ from docutils import nodes
 from docutils.writers.html5_polyglot import HTMLTranslator as BaseTranslator
 
 from sphinx import addnodes
-from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.builders import Builder
+from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 from sphinx.locale import admonitionlabels, _, __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
@@ -43,9 +44,17 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
 
     builder = None  # type: StandaloneHTMLBuilder
 
-    def __init__(self, builder, document):
+    def __init__(self, *args):
-        # type: (StandaloneHTMLBuilder, nodes.document) -> None
+        # type: (Any) -> None
-        super().__init__(builder, document)
+        if isinstance(args[0], nodes.document) and isinstance(args[1], Builder):
+            document, builder = args
+        else:
+            warnings.warn('The order of arguments for HTML5Translator has been changed. '
+                          'Please give "document" as 1st and "builder" as 2nd.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+            builder, document = args
+        super().__init__(document, builder)
+
         self.highlighter = self.builder.highlighter
         self.docnames = [self.builder.current_docname]  # for singlehtml builder
         self.manpages_url = self.config.manpages_url

sphinx/writers/latex.py

@@ -508,7 +508,7 @@ class LaTeXTranslator(SphinxTranslator):
 
     def __init__(self, document, builder):
         # type: (nodes.document, LaTeXBuilder) -> None
-        super().__init__(builder, document)
+        super().__init__(document, builder)
         self.body = []  # type: List[str]
 
         # flags

sphinx/writers/manpage.py

@@ -8,6 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
+import warnings
 from typing import Iterable, cast
 
 from docutils import nodes
@@ -17,6 +18,8 @@ from docutils.writers.manpage import (
 )
 
 from sphinx import addnodes
+from sphinx.builders import Builder
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.locale import admonitionlabels, _
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
@@ -26,7 +29,6 @@ from sphinx.util.nodes import NodeMatcher
 if False:
     # For type annotation
     from typing import Any, Dict  # NOQA
-    from sphinx.builders import Builder  # NOQA
 
 logger = logging.getLogger(__name__)
 
@@ -41,7 +43,7 @@ class ManualPageWriter(Writer):
         # type: () -> None
         transform = NestedInlineTransform(self.document)
         transform.apply()
-        visitor = self.builder.create_translator(self.builder, self.document)
+        visitor = self.builder.create_translator(self.document, self.builder)
         self.visitor = cast(ManualPageTranslator, visitor)
         self.document.walkabout(visitor)
         self.output = self.visitor.astext()
@@ -84,9 +86,16 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):
 
     _docinfo = {}  # type: Dict[str, Any]
 
-    def __init__(self, builder, document):
+    def __init__(self, *args):
-        # type: (Builder, nodes.document) -> None
+        # type: (Any) -> None
-        super().__init__(builder, document)
+        if isinstance(args[0], nodes.document) and isinstance(args[1], Builder):
+            document, builder = args
+        else:
+            warnings.warn('The order of arguments for ManualPageTranslator has been changed. '
+                          'Please give "document" as 1st and "builder" as 2nd.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+            builder, document = args
+        super().__init__(document, builder)
 
         self.in_productionlist = 0
 

sphinx/writers/texinfo.py

@@ -168,7 +168,7 @@ class TexinfoTranslator(SphinxTranslator):
 
     def __init__(self, document, builder):
         # type: (nodes.document, TexinfoBuilder) -> None
-        super().__init__(builder, document)
+        super().__init__(document, builder)
         self.init_settings()
 
         self.written_ids = set()        # type: Set[str]

sphinx/writers/text.py

@@ -396,7 +396,7 @@ class TextTranslator(SphinxTranslator):
 
     def __init__(self, document, builder):
         # type: (nodes.document, TextBuilder) -> None
-        super().__init__(builder, document)
+        super().__init__(document, builder)
 
         newlines = self.config.text_newlines
         if newlines == 'windows':