Skip to content

Commit

Permalink
Use Ubuntu 20.04, lualatex for readthedocs builds
Browse files Browse the repository at this point in the history
Read the Docs recently [added support for Ubuntu 20.04][2004]. This has
a newer version of TeX Live with better Unicode support. Specifically,
it is now possible to configure a list of fallback fonts to try for
characters missing from the current font, instead of displaying question
marks.

In the existing PDF docs, you can see some missing Unicode characters in
the descriptions for the pytest-addons-test and pytest-hammertime
plugins, which contain placeholder question marks.

Sadly, to get colour unicode support in PDFs, we will need to wait for
even newer software from Read the Docs, e.g., the `LuaHBTeX, Version
1.12.0 (TeX Live 2020/Debian)` of Ubuntu 20.10, to which one can add
`"Noto Color Emoji:mode=harf;",` to the fallback list.

[2004]: https://blog.readthedocs.com/new-build-specification/
  • Loading branch information
andrewdotn committed Oct 27, 2021
1 parent 14e0320 commit 4649191
Show file tree
Hide file tree
Showing 3 changed files with 17 additions and 3 deletions.
1 change: 1 addition & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ python:
path: .

build:
os: ubuntu-20.04
apt_packages:
- inkscape

Expand Down
1 change: 1 addition & 0 deletions changelog/9242.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Upgrade readthedocs configuration to use a [newer Ubuntu version](https://blog.readthedocs.com/new-build-specification/) with better unicode support for PDF docs.
18 changes: 15 additions & 3 deletions doc/en/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
import os
import shutil
import sys
from textwrap import dedent
from typing import List
from typing import TYPE_CHECKING

Expand All @@ -39,9 +40,20 @@
autodoc_typehints = "description"
todo_include_todos = 1

# Use a different latex engine due to possible Unicode characters in the documentation:
# https://docs.readthedocs.io/en/stable/guides/pdf-non-ascii-languages.html
latex_engine = "xelatex"
latex_engine = "lualatex"

latex_elements = {
'preamble': dedent("""
\directlua{
luaotfload.add_fallback("fallbacks", {
"Noto Serif CJK SC:style=Regular;",
"Symbola:Style=Regular;"
})
}
\setmainfont{FreeSerif}[RawFeature={fallback=fallbacks}]
""")
}

# -- General configuration -----------------------------------------------------

Expand Down

0 comments on commit 4649191

Please sign in to comment.