Add new API: Sphinx.add_latex_package()

Sphinx.add_latex_package() allows sphinx extensions to add latex packages.
It helps creating extensions for latex (for example, latex-theming)

doc/extdev/appapi.rst

@@ -288,6 +288,12 @@ package.
 
    .. versionadded:: 1.0
 
+.. method:: Sphinx.add_latex_package(packagename)
+
+   Add *packagename* to the list of packages that LaTeX source code will include.
+
+   .. versionadded:: 1.3
+
 .. method:: Sphinx.add_lexer(alias, lexer)
 
    Use *lexer*, which must be an instance of a Pygments lexer class, to

sphinx/application.py

@@ -694,6 +694,11 @@ class Sphinx(object):
             StandaloneHTMLBuilder.css_files.append(
                 posixpath.join('_static', filename))
 
+    def add_latex_package(self, packagename):
+        self.debug('[app] adding latex package: %r', packagename)
+        from sphinx.builders.latex import LaTeXBuilder
+        LaTeXBuilder.usepackages.append(packagename)
+
     def add_lexer(self, alias, lexer):
         self.debug('[app] adding lexer: %r', (alias, lexer))
         from sphinx.highlighting import lexers

sphinx/builders/latex.py

@@ -37,6 +37,7 @@ class LaTeXBuilder(Builder):
     format = 'latex'
     supported_image_types = ['application/pdf', 'image/png',
                              'image/gif', 'image/jpeg']
+    usepackages = []
 
     def init(self):
         self.docnames = []

sphinx/writers/latex.py

@@ -42,6 +42,7 @@ HEADER = r'''%% Generated by Sphinx.
 %(longtable)s
 \usepackage{sphinx}
 \usepackage{multirow}
+%(usepackages)s
 %(preamble)s
 
 \title{%(title)s}
@@ -153,6 +154,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         'fontpkg':         '\\usepackage{times}',
         'fncychap':        '\\usepackage[Bjarne]{fncychap}',
         'longtable':       '\\usepackage{longtable}',
+        'usepackages':     '',
         'preamble':        '',
         'title':           '',
         'date':            '',
@@ -234,6 +236,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 self.elements['fncychap'] = ''
         else:
             self.elements['classoptions'] += ',english'
+        if getattr(builder, 'usepackages', None):
+            usepackages = ('\\usepackage{%s}' % p for p in builder.usepackages)
+            self.elements['usepackages'] += "\n".join(usepackages)
         # allow the user to override them all
         self.elements.update(builder.config.latex_elements)
         if self.elements['extraclassoptions']:

tests/test_build_latex.py

@@ -91,3 +91,10 @@ def test_latex(app, status, warning):
                 assert False, 'latex exited with return code %s' % p.returncode
     finally:
         os.chdir(cwd)
+
+
+@with_app(buildername='latex')
+def test_latex_add_latex_package(app, status, warning):
+    app.add_latex_package('foo')
+    app.builder.build_all()
+    assert '\\usepackage{foo}' in (app.outdir / 'SphinxTests.tex').text()