Close #6762: latex: Allow to load additonal LaTeX packages

CHANGES

@@ -23,6 +23,8 @@ Features added
 * #267: html: Eliminate prompt characters of doctest block from copyable text
 * #6729: html theme: agogo theme now supports ``rightsidebar`` option
 * #6780: Add PEP-561 Support
+* #6762: latex: Allow to load additonal LaTeX packages via ``extrapackages`` key
+  of :confval:`latex_elements`
 
 Bugs fixed
 ----------

doc/latex.rst

@@ -226,6 +226,25 @@ into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
 
      .. versionadded:: 1.5
 
+  ``'extrapackages'``
+     Additional LaTeX packages.  For example:
+
+     .. code-block:: python
+
+         latex_elements = {
+             'packages': r'\usepackage{isodate}'
+         }
+
+     It defaults to empty.
+
+     The specified LaTeX packages will be loaded before
+     hyperref package and packages loaded from Sphinx extensions.
+
+     .. hint:: If you'd like to load additional LaTeX packages after hyperref, use
+               ``'preamble'`` key instead.
+
+     .. versionadded:: 2.3
+
   ``'footer'``
      Additional footer content (before the indices), default empty.
 

sphinx/templates/latex/latex.tex_t

@@ -35,6 +35,7 @@
 <%= sphinxsetup %>
 <%= fvset %>
 <%= geometry %>
+<%= extrapackages %>
 
 <%- for name, option in packages %>
 <%- if option %>

sphinx/writers/latex.py

@@ -155,6 +155,7 @@ DEFAULT_SETTINGS = {
                         '% Set up styles of URL: it should be placed after hyperref.\n'
                         '\\urlstyle{same}'),
     'contentsname':    '',
+    'extrapackages':   '',
     'preamble':        '',
     'title':           '',
     'release':         '',

tests/test_build_latex.py

@@ -1437,3 +1437,11 @@ def test_index_on_title(app, status, warning):
             '\\label{\\detokenize{contents:test-for-index-in-top-level-title}}'
             '\\index{index@\\spxentry{index}}\n'
             in result)
+
+
+@pytest.mark.sphinx('latex', testroot='basic',
+                    confoverrides={'latex_elements': {'extrapackages': r'\usepackage{foo}'}})
+def test_latex_elements_extrapackages(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'test.tex').text()
+    assert r'\usepackage{foo}' in result