#2725: latex builder: allow to use user-defined template file (experimental)

CHANGES

@@ -96,6 +96,7 @@ Features added
   prefixes from the index text of C++ objects.
 * C++, added concept directive. Thanks to mickk-on-cpp.
 * C++, added support for template introduction syntax. Thanks to mickk-on-cpp.
+* #2725: latex builder: allow to use user-defined template file (experimental)
 
 Bugs fixed
 ----------

doc/latex.rst

@@ -149,3 +149,12 @@ Let us illustrate here what can be modified by the second method.
    from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
    file. Sphinx aims at loading as few packages as are really needed for its
    default design.
+
+.. hint::
+
+   As an experimental feature, Sphinx can use user-defined template file for
+   LaTeX source if you have a file named ``_templates/latex.tex_t`` on your
+   project.  Now all template variables are unstable and undocumented.  They
+   will be changed in future version.
+
+   .. versionadded:: 1.5

sphinx/writers/latex.py

@@ -497,7 +497,12 @@ class LaTeXTranslator(nodes.NodeVisitor):
             'body': u''.join(self.body),
             'indices': self.generate_indices()
         })
-        return LaTeXRenderer().render(DEFAULT_TEMPLATE, self.elements)
+
+        template_path = path.join(self.builder.srcdir, '_templates', 'latex.tex_t')
+        if path.exists(template_path):
+            return LaTeXRenderer().render(template_path, self.elements)
+        else:
+            return LaTeXRenderer().render(DEFAULT_TEMPLATE, self.elements)
 
     def hypertarget(self, id, withdoc=True, anchor=True):
         if withdoc: