From a3ab764a5ba5134d1ef0f1f4abef0138ce478e15 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 17 Dec 2018 22:14:59 +0900 Subject: [PATCH] Reorder the arguments for translators --- CHANGES | 2 ++ sphinx/util/docutils.py | 4 ++-- sphinx/writers/html.py | 19 ++++++++++++++----- sphinx/writers/html5.py | 17 +++++++++++++---- sphinx/writers/latex.py | 2 +- sphinx/writers/manpage.py | 19 ++++++++++++++----- sphinx/writers/texinfo.py | 2 +- sphinx/writers/text.py | 2 +- 8 files changed, 48 insertions(+), 19 deletions(-) diff --git a/CHANGES b/CHANGES index cd640cb6b..fe923c602 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index 5d171b15c..4f6eb418e 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -392,8 +392,8 @@ class SphinxTranslator(nodes.NodeVisitor): This class is strongly coupled with Sphinx. """ - def __init__(self, builder, document): - # type: (Builder, nodes.document) -> None + def __init__(self, document, builder): + # type: (nodes.document, Builder) -> None super().__init__(document) self.builder = builder self.config = builder.config diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 0ef40e0f5..f7366767f 100644 --- a/sphinx/writers/html.py +++ b/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): - # type: (StandaloneHTMLBuilder, nodes.document) -> None - super().__init__(builder, document) + def __init__(self, *args): + # type: (Any) -> None + 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 diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index 077b93af4..2a8380d73 100644 --- a/sphinx/writers/html5.py +++ b/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): - # type: (StandaloneHTMLBuilder, nodes.document) -> None - super().__init__(builder, document) + def __init__(self, *args): + # type: (Any) -> None + 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 diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 4f3b3cb33..4b0914a16 100644 --- a/sphinx/writers/latex.py +++ b/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 diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 74c17fd6c..8d311acbc 100644 --- a/sphinx/writers/manpage.py +++ b/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): - # type: (Builder, nodes.document) -> None - super().__init__(builder, document) + def __init__(self, *args): + # type: (Any) -> None + 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 diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index adc05359c..f4af84edf 100644 --- a/sphinx/writers/texinfo.py +++ b/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] diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index f8805108c..3897f4e4c 100644 --- a/sphinx/writers/text.py +++ b/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':