sphinx
/ / 点击 / 阅读耗时 7 分钟参考资料
- sphinx官方-主页
- sphinx官方-config.py ：生成html、latex以及转换成pdf的多数格式均在这个文件里进行配置
- sphtinx官方-模板：本次使用第三方模板 sphinx_rtd_theme
- sphinx官方-latex输出配置说明
- sphinx官方-创建指令
- sphinx使用手册中文译文
- 博客1：环境搭建、快速构建
环境搭建
环境搭建参考博客1。
- 安装python
- 安装sphinx
- 安装textlive（可选）
- 安装汉字字体（可选）
- 以装宋体为例（simsun.ttc），字体文件要注意是否可用
- 安装第三方模板（可选）
构建文档
快速构建参考博客1 。
文档结构配置
入口文件：
1
2
3
4
5
6
7
8
9
10
11
12
13.. toctree::
:maxdepth: 2
:hidden:
README
book/UOS4.0介绍
book/快速入门/index
book/UOS项目平台/index
book/UOS管理平台/index
book/UOS计费系统/index
book/UOS审批系统/index
book/UOS存储平台/index
book/UOS工单系统/index.. toctree::：这个指令用来设置文档组织结构，其中:maxdepth: 2：用来设置目录显示层级:hidden: 用来设置是否在每个主页（index）中显示该目录:number:用来设置是否在目录前列出编号:caption: 目录用来修改在pdf中index前显示的文字，更多设置详见官方配置文档
- 下面的部分表示组织起来的结构，这里分别是各个章节的主页，会显示章节标题。每个章节的主页中再以此种形式列出各自的结构组织。
config.py配置选项
值得注意的通用配置
- 文档格式：
source_suffix = '.rst' - 编码类型（中文一定要用这个）：
source_encoding = 'utf-8' - 文档入口：
master_doc = 'index'
- 文档格式：
值得注意的html输出配置
- 使用第三方模板（可以参考sphtinx官方-模板 、博客1）
- 文档开头：
import sphinx_rtd_theme - “Options for HTML output”部分：
html_theme = 'sphinx_rtd_theme'
- 文档开头：
- html_sidebars: html侧边栏显示（可以参考sphtinx官方-模板）
- 不显示文档源文件：
html_show_sourcelink = False - 不在底边显示“sphinx创建”字样：
html_show_sphinx = False
- 使用第三方模板（可以参考sphtinx官方-模板 、博客1）
latex输出配置1（用于转换pdf）
处理引擎配置：
latex_engine = 'xelatex'latex_elements配置中：
纸张大小：
'papersize': 'a4paper'字体大小：
'pointsize': '10pt'preamble配置：
1
2
3
4
5
6
7
8
9
10
11
12'''
\\usepackage{xeCJK}
\\usepackage{indentfirst}
\\setlength{\\parindent}{2em}
\\setCJKmainfont{SimSun} #针对中文使用中文字体
\\setCJKmonofont[Scale=0.9]{SimSun}
\\setCJKfamilyfont{song}{SimSun}
\\setCJKfamilyfont{sf}{SimSun}
\\XeTeXlinebreakskip = 0pt plus 1pt
\\setcounter{tocdepth}{2} #目录显示的层级
\\setcounter{secnumdepth}{0} #文档中标题前显示的编号等级
'''
单页输出：
'classoptions': ',oneside'章节样式：
'fncychap': ''空字符不使用章节latex_documents配置的最后一项： 使用
'howto'，chm格式。
latex输出配置2（用于输出pdf）
latex输出配置1输出的pdf不带页码，为了解决这个问题：
- 增加：
latex_toplevel_sectioning = 'section' - 修改：’howto’改为’manual’
- 增加：
表格配置
表格配置指令使用：.. tabularcolumns:: column spec ，放在表格所在文档表格前，详见：官方配置文档 。注意：超过30行的表格latex无法自动控制宽度，可以使用p{width}手动控制 。
转换pdf指令
首先生成latex文档，之后使用xelatex（主要是为了处理中文）生成pdf，第二次使用xelatex为了生成pdf文档目录和文档中的连接。
- make latex
- cd build/latex
- xelatex *.tex
- xelatex *.tex
关于转换pdf的方法
试用过四种方法，只有xelatex成功。以下是其他三种未成功的方法：
- latexpdf指令：生成文档错误，未继续；
- 借用rst2pdf：sphinx官网上有说rst2pdf已停止维护，针对最新版可能有问题，实际使用中英文能够正常显示，中文显示未乱码，即便编码规则设定为utf-8依然不能正常显示；
- 借用rinohtype：sphinx官方推荐的一种直接转换pdf的方法。但实际使用中发现转换时间过长，且依然没有能处理好中文显示的问题。
全文完。