常见问题集锦

2.6. 常见问题集锦#

2.6.1. 中文问题#

源编码#

在reST使用Unicode字符可以容易的包含特殊字符如破折号, 版权标志。 Sphinx 默认源文件使用UTF-8 编码; 你可以通过修改 conf.py 文件的 source_encoding 的配置值改变编码.

中文文档问题#

在使用Sphinx发布**中文文档**生成LaTex或PDF文件时, 会发现报出如下类似错误

! Package inputenc Error: Unicode char \u8:引 not set up for use with LaTeX.

这是因为, Sphinx默认使用 pdflatex 编译文档, 而要让 latex 支持中文, 需要包含一些中文包. 最好的解决方案是使用 xelatex 编译引擎并包含 CTEX 包, 只需要修改两个文件：

  1. 修改 conf.py 文件（约220行）

添加如下代码, 使得程序自动在latex文件的导言区加入包引用

# -- Options for LaTeX output ---------------------------------------------

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': '',

# Latex figure (float) alignment
#'figure_align': 'htbp',

# Using Package for ZH
'preamble' : r'''
\usepackage{ctex}
''',
}

添加的代码为 # Using Package for ZH 下面的三行, 然后保存.

  1. 修改 Makefile 文件（约142行）

添加如下代码中的第5行代码, 即可更改编译引擎为xelatex

.PHONY: latexpdf
latexpdf:
    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    @echo "Running LaTeX files through pdflatex..."
    sed -i s/pdflatex/xelatex/ $(BUILDDIR)/latex/Makefile
    $(MAKE) -C $(BUILDDIR)/latex all-pdf
    @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

修改后保存, 然后终端运行 make latexpdf 即可看到PDF成功生成的提示, 在 build/latex 文件夹中可以找到.

中文乱码问题#

问题描述: 如果你使用Sphinx生成含有中文字符的静态网页时, 当你你视图点击 View page source 时可能发现中文乱码的问题, 如下图:

_images/result-changeto-utf8.png

这时要确保编码的匹配一致性: 源码文件编码, 源码编码设置值, 浏览器编码 要一致, Sphinx采用 UTF-8 来支持不同特殊的字符. 所以, 请检查以上三项: 第二项是要确保 conf.py 文件中的编码为 UTF-8, 即 #source_encoding = 'utf-8-sig', 这也是默认值; 第三项, 可参见下图更改浏览器编码:

_images/genggaibianma.png

如何支持中文搜索#

注解

旧版本的 Sphinx 默认是不支持中文搜索的，要支持中文搜索需要用到 jieba 模块，安装起来比较麻烦，这里不作介绍。

新版本的 Sphinx 正式支持中文搜索，使用起来很简单。

安装

pip install jieba

在 conf.py 文件的最后一行加上

html_search_language = 'zh'

然后重新生成就可以了。

2.6.2. 常用 reStructuredText 标记#

引用：         [1]_            .. [1]
脚注：         [#f1]_          .. [#f1]
强制换行：     | string
Warning

在使用引用和脚注时，中括号的后面必须带至少一个空格，不然无法正常生成 html 文件。

如何固定主题 alabaster 的侧边栏

在该项目的 conf.py 下加入以下语句

html_theme_options = {
    'fixed_sidebar': True,
}

2.6.3. 如何使用原始的 html 标签#

代码：

.. raw:: html

    <hr />这里是分割线 <hr />

效果：

这里是分割线
目录