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

@@ -90,8 +90,6 @@ Using the theme
 
    - ``project``
    - ``html_last_updated_fmt``
-   - ``latex_engine``
-   - ``latex_elements``
 
 #. Configure version-related options.
 

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):

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.