diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 4fed158cb..35d226a5e 100644 --- a/doc/extdev/appapi.rst +++ b/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 diff --git a/sphinx/application.py b/sphinx/application.py index 13a2d272a..37db1f00c 100644 --- a/sphinx/application.py +++ b/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 diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index bf7991cfb..5683ade25 100644 --- a/sphinx/builders/latex.py +++ b/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 = [] diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index abc7ed75a..408c5fff5 100644 --- a/sphinx/writers/latex.py +++ b/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']: diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 9e4c11d59..9131ede01 100644 --- a/tests/test_build_latex.py +++ b/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()