常见问题集锦

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原生只支持英文搜索, 参考 让sphinx支持简体中文搜索的插件 , 来实现中文搜索的支持, 下载插件并安装, 具体过程如下：

  1. 安装结巴分词, Linux： sudo pip install jieba , Windows： pip install jieba

  2. 复制文件 zh_CN.py 到sphinx的search目录下, Linux： /usr/lib/python2.7/dist-packages/sphinx/search, Windows： C:\Python27\Lib\site-packages\sphinx\search

  3. 打开 search 目录下的 __init__.py 文件, 找到代码, 添加对中文的支持：

    from sphinx.search import en, ja
languages = {
    'en': en.SearchEnglish,
    'ja': ja.SearchJapanese,
}

修改成：

from sphinx.search import en, ja, zh_CN
languages = {
    'en': en.SearchEnglish,
    'ja': ja.SearchJapanese,
    'zh_CN': zh_CN.SearchChinese
}

  4. 修改 conf.py 文件, 将语言设置成 language = 'zh_CN' , 保存然后重新编译 make html 即可.

关于CJK支持请参考: CJK支持 .

中文乱码问题#

问题描述: 如果你使用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 正式支持中文搜索啦。

旧版本的 Sphinx 默认是不支持中文搜索的，要支持中文搜索需要用到 jieba 模块。 使用起来很简单。

1.安装

pip install jieba

2.使用 在 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 />

效果：

这里是分割线
目录