Closed eloquence closed 6 days ago
The build error is due LaTeX stumbling over the ⚙️ character. If we want to keep it, that's probably fixable (change the branch in deploy/Dockerfile
and debug builds with podman build -t sdwdocs -f deploy/Dockerfile .
); otherwise I'd suggest changing that to "Gear symbol".
The build error is due LaTeX stumbling over the ⚙️ character. If we want to keep it, that's probably fixable (change the branch in
deploy/Dockerfile
and debug builds withpodman build -t sdwdocs -f deploy/Dockerfile .
); otherwise I'd suggest changing that to "Gear symbol".
Via https://github.com/sphinx-doc/sphinx/issues/10469 I found https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_engine - I can experiment with that a bit before giving up on unicode.
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.
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
I'm out of timebox so I'm going to say that we won't be able to use a gear emoji for the 1.0.0 release. We should aim to switch to xelatex or another Unicode supporting rendering engine though.
(I've copied the above thread to https://github.com/freedomofpress/securedrop-docs/issues/576 so we don't forget about this)
Most of this was incorporated into #228 (thanks :); I spotted a couple of menu references that still need to be updated, will open a smaller PR for those.
The new Q menu is fairly complex, and describing it in text alone is tricky. To recap:
I've therefore adopted the following conventions:
Refs #221