Support LaTeX Theming; a set of document class settings (refs: #6672)

1 files changed, 44 insertions, 15 deletions

diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
index 317b74fdb..cfce52f7f 100644
--- a/sphinx/writers/latex.py
+++ b/sphinx/writers/latex.py
@@ -23,7 +23,9 @@ from docutils.nodes import Element, Node, Text
 
 from sphinx import addnodes
 from sphinx import highlighting
-from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
+from sphinx.deprecation import (
+    RemovedInSphinx40Warning, RemovedInSphinx50Warning, deprecated_alias
+)
 from sphinx.domains import IndexEntry
 from sphinx.domains.std import StandardDomain
 from sphinx.errors import SphinxError
@@ -43,6 +45,7 @@ except ImportError:
 if False:
     # For type annotation
     from sphinx.builders.latex import LaTeXBuilder
+    from sphinx.builders.latex.theming import Theme
 
 
 logger = logging.getLogger(__name__)
@@ -93,9 +96,16 @@ class LaTeXWriter(writers.Writer):
     def __init__(self, builder: "LaTeXBuilder") -> None:
         super().__init__()
         self.builder = builder
+        self.theme = None  # type: Theme
 
     def translate(self) -> None:
-        visitor = self.builder.create_translator(self.document, self.builder)
+        try:
+            visitor = self.builder.create_translator(self.document, self.builder, self.theme)
+        except TypeError:
+            warnings.warn('LaTeXTranslator now takes 3rd argument; "theme".',
+                          RemovedInSphinx50Warning)
+            visitor = self.builder.create_translator(self.document, self.builder)
+
         self.document.walkabout(visitor)
         self.output = cast(LaTeXTranslator, visitor).astext()
 
@@ -281,9 +291,15 @@ class LaTeXTranslator(SphinxTranslator):
     # sphinx specific document classes
     docclasses = ('howto', 'manual')
 
-    def __init__(self, document: nodes.document, builder: "LaTeXBuilder") -> None:
+    def __init__(self, document: nodes.document, builder: "LaTeXBuilder",
+                 theme: "Theme" = None) -> None:
         super().__init__(document, builder)
         self.body = []  # type: List[str]
+        self.theme = theme
+
+        if theme is None:
+            warnings.warn('LaTeXTranslator now takes 3rd argument; "theme".',
+                          RemovedInSphinx50Warning)
 
         # flags
         self.in_title = 0
@@ -306,21 +322,32 @@ class LaTeXTranslator(SphinxTranslator):
         # sort out some elements
         self.elements = self.builder.context.copy()
 
-        # but some have other interface in config file
-        self.elements['wrapperclass'] = self.format_docclass(document.get('docclass'))
-
-        # we assume LaTeX class provides \chapter command except in case
-        # of non-Japanese 'howto' case
+        # initial section names
         self.sectionnames = LATEXSECTIONNAMES[:]
-        if document.get('docclass') == 'howto':
-            docclass = self.config.latex_docclass.get('howto', 'article')
-            if docclass[0] == 'j':  # Japanese class...
-                pass
-            else:
+
+        if self.theme:
+            # new style: control sectioning via theme's setting
+            #
+            # .. note:: template variables(elements) are already assigned in builder
+            docclass = self.theme.docclass
+            if self.theme.toplevel_sectioning == 'section':
                 self.sectionnames.remove('chapter')
         else:
-            docclass = self.config.latex_docclass.get('manual', 'report')
-        self.elements['docclass'] = docclass
+            # old style: sectioning control is hard-coded
+            # but some have other interface in config file
+            self.elements['wrapperclass'] = self.format_docclass(self.settings.docclass)
+
+            # we assume LaTeX class provides \chapter command except in case
+            # of non-Japanese 'howto' case
+            if document.get('docclass') == 'howto':
+                docclass = self.config.latex_docclass.get('howto', 'article')
+                if docclass[0] == 'j':  # Japanese class...
+                    pass
+                else:
+                    self.sectionnames.remove('chapter')
+            else:
+                docclass = self.config.latex_docclass.get('manual', 'report')
+            self.elements['docclass'] = docclass
 
         # determine top section level
         self.top_sectionlevel = 1
@@ -472,6 +499,8 @@ class LaTeXTranslator(SphinxTranslator):
     def format_docclass(self, docclass: str) -> str:
         """ prepends prefix to sphinx document classes
         """
+        warnings.warn('LaTeXWriter.format_docclass() is deprecated.',
+                      RemovedInSphinx50Warning, stacklevel=2)
         if docclass in self.docclasses:
             docclass = 'sphinx' + docclass
         return docclass