diff --git a/CHANGES b/CHANGES index 5497d94a2..6473ed44d 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/latex.rst b/doc/latex.rst index 2501d1594..7321f964b 100644 --- a/doc/latex.rst +++ b/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. diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index 2beac82c9..a0a5a26b1 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -35,6 +35,7 @@ <%= sphinxsetup %> <%= fvset %> <%= geometry %> +<%= extrapackages %> <%- for name, option in packages %> <%- if option %> diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 832d34dfa..364067497 100644 --- a/sphinx/writers/latex.py +++ b/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': '', diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 8410bbd03..c48399f1b 100644 --- a/tests/test_build_latex.py +++ b/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