readthedocs.org编译项目的时候默认打开pdf和epub选项，中间貌似是基于LaTex的，字体问题非常头疼，之前都是在readthedocs.org项目中的高级选项选择把pdf编译禁掉，才会build pass。
最近在网上找到了解决办法：https://github.com/JuliaCN/julia_zh_cn/blob/master/conf.py。
在conf.py中修改latex_elements即可：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
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. #'preamble': '', 'preamble': r''' \hypersetup{unicode=true} \usepackage{CJKutf8} \DeclareUnicodeCharacter{00A0}{\nobreakspace} \DeclareUnicodeCharacter{2203}{\ensuremath{\exists}} \DeclareUnicodeCharacter{2200}{\ensuremath{\forall}} \DeclareUnicodeCharacter{2286}{\ensuremath{\subseteq}} \DeclareUnicodeCharacter{2713}{x} \DeclareUnicodeCharacter{27FA}{\ensuremath{\Longleftrightarrow}} \DeclareUnicodeCharacter{221A}{\ensuremath{\sqrt{}}} \DeclareUnicodeCharacter{221B}{\ensuremath{\sqrt[3]{}}} \DeclareUnicodeCharacter{2295}{\ensuremath{\oplus}} \DeclareUnicodeCharacter{2297}{\ensuremath{\otimes}} \begin{CJK}{UTF8}{gbsn} \AtEndDocument{\end{CJK}} ''', } |
这里要注意的是，这段代码是配置LaTex，所以这些字符串必须加r，不要让pyhton解释。
所以务必检查一下几项：
- 不要全局导入
__future__.unicode_literals，这会让这段代码编程unicode解释，readthedocs编译的时候会出字符问题。 - 检查项目中全局替换的部分(例如
rst_epilog），如果修改到源文件，那么务必手动添加u前缀，否则会出现编码错误。
目前我只遇到这两个问题，解决之后readthedoc.org就编译通过了。不过好像编译出的pdf并不是特别美观。