freedomofpress / securedrop-docs

Documentation for the SecureDrop project
https://docs.securedrop.org/
Other
22 stars 26 forks source link

Use Unicode-friendly renderer for PDF docs #576

Open legoktm opened 1 month ago

legoktm commented 1 month ago

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. 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