From 10ee758d42e122f196d1e339208406218bac0205 Mon Sep 17 00:00:00 2001
From: Kunal Mehta <legoktm@debian.org>
Date: Wed, 29 Jul 2026 15:14:25 -0400
Subject: [PATCH] Switch to `make singlehtml` + Chromium for PDF output

Instead of going through LaTeX, which has some limitations (e.g. can't
use newer emojis), we can use sphinx's pre-existing "singlehtml" target,
and just have a browser print it to PDF. Chromium has a better CLI setup
for this, but in the future we can swap to Firefox if desired.

I think for the most part this will be a nicer experience for users,
because it'll be much closer to what's already online (some CSS is
different), and because it's just HTML, there'll be far less less
gotchas of things that work in HTML mode but not in PDF mode.
---
 deploy/Dockerfile |  4 ++--
 deploy/build      | 13 ++++++++--
 docs/conf.py      | 60 -----------------------------------------------
 3 files changed, 13 insertions(+), 64 deletions(-)

diff --git a/deploy/Dockerfile b/deploy/Dockerfile
index 4efbe30a..a0dcbb35 100644
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -1,7 +1,7 @@
 FROM debian:trixie AS sphinx
 
 ARG GIT_BRANCH=main
-RUN apt-get -q update && apt-get -qy upgrade && apt-get -qy install git make latexmk texlive-latex-extra python3-poetry
+RUN apt-get -q update && apt-get -qy upgrade && apt-get -qy install git make chromium python3-poetry
 COPY ./ .
 RUN poetry install
 RUN deploy/build $GIT_BRANCH
@@ -14,4 +14,4 @@ RUN mkdir -p /opt/nginx/run /opt/nginx/webroot/en/latest && chown -R nginx:nginx
 
 USER nginx
 COPY --from=sphinx --chown=nginx:nginx build/latest/html/ /opt/nginx/webroot/en/latest/
-COPY --from=sphinx --chown=nginx:nginx build/latest/latex/SecureDropDevDocs.pdf /opt/nginx/webroot/en/latest/
+COPY --from=sphinx --chown=nginx:nginx build/latest/singlehtml/SecureDropDevDocs.pdf /opt/nginx/webroot/en/latest/
diff --git a/deploy/build b/deploy/build
index 1458b4cd..ee4e2448 100755
--- a/deploy/build
+++ b/deploy/build
@@ -9,8 +9,17 @@ do_build() {
     git checkout "$1"
 
     make html
-    # Remote-loaded SVGs will cause a build failure unless we use force-mode.
-    LATEXMKOPTS="-interaction=nonstopmode -f" make latexpdf || true
+    # Concatenate every page into one HTML file, then have headless Chromium
+    # print it to PDF. This replaces the old LaTeX-based `make latexpdf`.
+    make singlehtml
+    chromium \
+        --headless \
+        --no-sandbox \
+        --disable-gpu \
+        --virtual-time-budget=120000 \
+        --no-pdf-header-footer \
+        --print-to-pdf=docs/_build/singlehtml/SecureDropDevDocs.pdf \
+        "file://$(pwd)/docs/_build/singlehtml/index.html"
 
     mkdir -p build
     mv docs/_build "build/${2}"
diff --git a/docs/conf.py b/docs/conf.py
index d11a7be8..a8277481 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -200,66 +200,6 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = "SecureDropDevDocs"
 
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    # Neither of:
-    #     \usepackage[T1]{fontenc}
-    #     \usepackage{textcomp}
-    # seem to make this magically work, so define individual characters.
-    # Also,
-    #     \usepackage{svg}
-    # does not seem to allow inclusion of the Weblate status badge (over HTTPS,
-    # which may be the problem).
-    'preamble': r'''
-    \DeclareUnicodeCharacter{25B6}{$\blacktriangleright$}
-    \DeclareUnicodeCharacter{25B8}{$\blacktriangleright$}
-    \DeclareUnicodeCharacter{2B06}{$\uparrow$}
-    \DeclareUnicodeCharacter{2B07}{$\downarrow$}
-    \DeclareUnicodeCharacter{201C}{\textquotedblleft}
-    \DeclareUnicodeCharacter{201D}{\textquotedblright}
-    \DeclareUnicodeCharacter{00E2}{\^a}
-    \DeclareUnicodeCharacter{20AC}{\euro}
-    \DeclareUnicodeCharacter{0153}{\oe}
-    \DeclareUnicodeCharacter{FFFD}{$\blacklozenge$}
-    ''',
-    # Latex figure (float) alignment
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "SecureDropDevDocs.tex", u"SecureDrop Developer Documentation", author, "manual"),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples