Unfortunately switching to xelatex is only half of the solution, then we need to find a font that supports the gear icon (⚙ (U+2699)) in bold. Neither Noto nor DejaVu Serif have it. For some reason trying to set \setmainfont{Noto Color Emoji} doesn't work. Using Symbola does though, but I'm not super impressed with the rest of that font's quality.
For posterity, here's what I had tried in the workstation-docs repo:
diff --git a/deploy/Dockerfile b/deploy/Dockerfile
index e434507..f27947f 100644
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -1,7 +1,8 @@
FROM debian:bookworm 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 latexmk texlive-xetex texlive-latex-extra python3-poetry \
+ fonts-freefont-otf font-symbola texlive-fonts-extra-links
COPY ./ .
RUN poetry install
RUN deploy/build $GIT_BRANCH
diff --git a/docs/conf.py b/docs/conf.py
index 4a59811..a105b6e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -160,7 +160,13 @@ htmlhelp_basename = 'SecureDropWorkstationdoc'
# -- Options for LaTeX output ---------------------------------------------
+latex_engine = 'xelatex'
latex_elements = {
+ 'fontpkg': r'''
+\setmainfont{DejaVu Serif}
+\setsansfont{DejaVu Sans}
+\setmonofont{DejaVu Sans Mono}
+''',
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
@@ -177,7 +183,6 @@ latex_elements = {
# seem to make this magically work, so define individual characters.
'preamble': r'''
\usepackage{amssymb}
- \DeclareUnicodeCharacter{25B8}{$\blacktriangleright$}
'''
# Latex figure (float) alignment
In https://github.com/freedomofpress/securedrop-workstation-docs/pull/222 we tried to add a unicode symbol, ⚙ (U+2699), to the docs, which failed because our current latex PDF renderer isn't really great with unicode.
Via https://github.com/sphinx-doc/sphinx/issues/10469 I found https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_engine
Unfortunately switching to
xelatex
is only half of the solution, then we need to find a font that supports the gear icon (⚙ (U+2699)
) in bold. Neither Noto nor DejaVu Serif have it. For some reason trying to set\setmainfont{Noto Color Emoji}
doesn't work. UsingSymbola
does though, but I'm not super impressed with the rest of that font's quality.For posterity, here's what I had tried in the workstation-docs repo: