Add options argument to Sphinx.add_latex_package()

doc/extdev/appapi.rst

@@ -288,9 +288,15 @@ package.
 
    .. versionadded:: 1.0
 
-.. method:: Sphinx.add_latex_package(packagename)
+.. method:: Sphinx.add_latex_package(packagename, options=None)
 
    Add *packagename* to the list of packages that LaTeX source code will include.
+   If you provide *options*, it will be taken to `\usepackage` declaration.
+
+   .. code-block:: python
+
+      app.add_latex_package('mypackage')             # => \usepackage{mypackage}
+      app.add_latex_package('mypackage', 'foo,bar')  # => \usepackage[foo,bar]{mypackage}
 
    .. versionadded:: 1.3
 

sphinx/application.py

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

sphinx/writers/latex.py

@@ -237,7 +237,12 @@ class LaTeXTranslator(nodes.NodeVisitor):
         else:
             self.elements['classoptions'] += ',english'
         if getattr(builder, 'usepackages', None):
-            usepackages = ('\\usepackage{%s}' % p for p in builder.usepackages)
+            def declare_package(packagename, options=None):
+                if options:
+                    return '\\usepackage[%s]{%s}' % (options, packagename)
+                else:
+                    return '\\usepackage{%s}' % (packagename,)
+            usepackages = (declare_package(*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)

tests/test_build_latex.py

@@ -96,5 +96,7 @@ def test_latex(app, status, warning):
 @with_app(buildername='latex')
 def test_latex_add_latex_package(app, status, warning):
     app.add_latex_package('foo')
+    app.add_latex_package('bar', 'baz')
     app.builder.build_all()
     assert '\\usepackage{foo}' in (app.outdir / 'SphinxTests.tex').text()
+    assert '\\usepackage[baz]{bar}' in (app.outdir / 'SphinxTests.tex').text()