From 2b258f0380ac69c948138fa425f01853fbedb63a Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Tue, 17 Sep 2019 16:23:20 +0100
Subject: [PATCH] Merge, rather than overwrite, LaTeX settings

This leads to more predictable behavior.

Change-Id: I3a9d96c4896a0d5ccc85b74562d35852a837f29f
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1843527
---
 doc/source/index.rst                          |  2 --
 openstackdocstheme/ext.py                     | 27 ++++++++++++++-----
 .../merge-latex-options-242f10c932f0e6af.yaml |  9 +++++++
 3 files changed, 29 insertions(+), 9 deletions(-)
 create mode 100644 releasenotes/notes/merge-latex-options-242f10c932f0e6af.yaml

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 61e4af64..65d43728 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -90,8 +90,6 @@ Using the theme
 
    - ``project``
    - ``html_last_updated_fmt``
-   - ``latex_engine``
-   - ``latex_elements``
 
 #. Configure version-related options.
 
diff --git a/openstackdocstheme/ext.py b/openstackdocstheme/ext.py
index 4e5e924c..f0a3a16d 100644
--- a/openstackdocstheme/ext.py
+++ b/openstackdocstheme/ext.py
@@ -18,6 +18,7 @@ except ImportError:
     import ConfigParser as configparser
 import os
 import subprocess
+import textwrap
 
 import dulwich.repo
 from pbr import packaging
@@ -341,17 +342,29 @@ def _builder_inited(app):
 
     theme_logo = paths.get_theme_logo_path(app.config.html_theme)
     pdf_theme_path = paths.get_pdf_theme_path(app.config.html_theme)
-
-    app.config.latex_engine = 'xelatex'
-    app.config.latex_elements = {
+    latex_elements = {
         'papersize': 'a4paper',
         'pointsize': '11pt',
         'figure_align': 'H',
         'classoptions': ',openany',
-        'preamble': r"""
-\usepackage{""" + pdf_theme_path + r"""}
-\newcommand{\openstacklogo}{""" + theme_logo + """}
-"""}
+    }
+
+    if app.config.latex_elements:
+        latex_elements.update(app.config.latex_elements)
+
+    preamble = textwrap.dedent(
+        r"""
+        \usepackage{%s}
+        \\newcommand{\openstacklogo}{%s}
+        """
+    ) % (pdf_theme_path, theme_logo)
+
+    if 'preamble' in latex_elements:
+        preamble += latex_elements['preamble']
+
+    latex_elements['preamble'] = preamble
+
+    app.config.latex_elements = latex_elements
 
 
 def setup(app):
diff --git a/releasenotes/notes/merge-latex-options-242f10c932f0e6af.yaml b/releasenotes/notes/merge-latex-options-242f10c932f0e6af.yaml
new file mode 100644
index 00000000..caa5d17e
--- /dev/null
+++ b/releasenotes/notes/merge-latex-options-242f10c932f0e6af.yaml
@@ -0,0 +1,9 @@
+---
+fixes:
+  - |
+    The ``latex_engine`` and ``latex_elements`` options, which were previously
+    always overridden by the extension, will now be merged with user
+    configuration. If ``latex_engine`` is configured by the user, this will be
+    used in-place of the default. If ``latex_elements``, a dictionary, is
+    configured, the values provided by the user will be merged with the
+    defaults with user-provided defaults preferred.