# sphinx中文文档在readthedocs编译PDF失败的处理

当撰写好的sphinx文档上传到github，并同步到readthedocs.org，此时会发现编译错误，这是因为默认打开到pdf和epub选项是基于LaTex的，对字体处理有要求。

解决的方法是编辑`conf.py`，修改`latex_elements`设置段落：

```python
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前缀，否则会出现编码错误。

## 参考

* [解决在readthedocs编译PDF含中文的问题](https://www.kawabangga.com/posts/2331) - 本文即转载自这片文档，测试有效
* [使用ReadtheDocs托管文档](https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html) - 非常详细的RedtheDocs托管介绍，建议参考


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://huataihuang.gitbook.io/cloud-atlas-draft/develop/doc/sphinx/readthedocs_compile_fail.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.