转载地址：https://bbs.huaweicloud.com/forum/thread-80280-1-1.html

作者：zhany

Sphinx输出MindSpore教程PDF文档操作指南

• Sphinx输出MindSpore教程PDF文档操作指南
• 概述
• 整体流程
• 环境依赖

• 环境准备
• 本地环境准备
• Docker环境准备

• 修改配置文件
• 输出PDF文档
• 本地输出PDF文档
• 使用Docker输出PDF文档
• 注意事项

• 结语

python-sphinx xelatex pdf

概述

MarkDown——作为一种轻量级标记语言，允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学公式都有支持，目前许多网站都广泛使用Markdown来撰写帮助文档或是用于论坛上发表消息。固然输出HTML版本的教程用户可以很方便的查阅，但是却不具有印刷风格的阅读体验，不便于存档保存，更不能用于印刷发行。作为业界流行的文档输出工具，Sphinx从2.0.0版本开始已经支持使用xelatex引擎，我们可以利用xelatex很方便的输出高质量的印刷版本的PDF文档。关于Sphinx的基本使用可参考《windows环境下配置sphinx输出html文档》，接下来我们通过输出MindSpore推理教程PDF中文文档为例，介绍如何使用Sphinx输出PDF文档。

整体流程

环境依赖

• python3
• sphinx: 版本高于2.0.0
• ubuntu：需有make编译工具

环境准备

我们可以通过本地安装依赖或利用Docker Hub两种方式完成相关环境的配置：

本地环境准备

在安装有python3和具有make编译能力的ubuntu系统（推荐使用ubuntu系统来解决相关依赖问题）上，执行以下命令，安装xelatex和sphinx。

1. 安装sphinx及相关依赖。
   将MindSpore推理教程的源文件下载到本地后，进入到该目录下:
   
1. 
   inference
2. 
   ├── Makefile
3. 
   ├── requirements.txt
4. 
   ├── source_en
5. 
   │ ├── conf.py
6. 
   │ ├── index.rst
7. 
   │ ├── multi_platform_inference_ascend_310.md
8. 
   │ ├── multi_platform_inference_ascend_910.md
9. 
   │ ├── multi_platform_inference_cpu.md
10. 
    │ ├── multi_platform_inference_gpu.md
11. 
    │ ├── multi_platform_inference.md
12. 
    │ ├── serving.md
13. 
    │ └── _static
14. 
    └── source_zh_cn
15. 
    ├── conf.py
16. 
    ├── index.rst
17. 
    ├── multi_platform_inference_ascend_310.md
18. 
    ├── multi_platform_inference_ascend_910.md
19. 
    ├── multi_platform_inference_cpu.md
20. 
    ├── multi_platform_inference_gpu.md
21. 
    ├── multi_platform_inference.md
22. 
    ├── serving.md
23. 
    └── _static

执行以下命令安装sphinx：
$ pip install -r requirements.txt

1. 安装xelatex。
   使用apt管理器执行以下命令安装xelatex引擎（整体约为3G大小，用时较久，请耐心等待）：
   
1. 
   $ sudo apt-get install texlive-lang-chinese \
2. 
   graphviz \
3. 
   imagemagick \
4. 
   make \
5. 
   latexmk \
6. 
   lmodern \
7. 
   texlive-latex-recommended \
8. 
   texlive-latex-extra \
9. 
   texlive-fonts-recommended \
10. 
    texlive-fonts-extra \
11. 
    texlive-lang-cjk \
12. 
    texlive-luatex \
13. 
    texlive-xetex \
14. 
    texlive-latex-extra-doc

Docker环境准备

我们也可以使用Docker安装所需的环境。详细可参考https://github.com/sphinx-doc/docker。

执行以下命令从Docker Hub获取sphinx镜像:

$ sudo docker pull sphinxdoc/sphinx-latexpdf:2.4.4

修改配置文件

进入到本地MindSpore推理教程源文件目录，配置文件位置为source_zh_cn/config.py, 在末尾添加如下所示代码：

1. 
   latex_engine = 'xelatex'
2. 
   latex_use_xindy = False
3. 
   latex_elements = {
4. 
   'preamble': '\\usepackage[UTF8]{ctex}\n',
5. 
   'papersize': 'a4paper',
6. 
   'pointsize': '10pt',
7. 
   }
8. 
   latex_toplevel_sectioning = None
9. 
   latex_domain_indices = True
10. 
    latex_show_pagerefs = False
11. 
    latex_logo = '{logo_path}'
12. 
    master_doc = 'index'

• 其中logo_path为封面logo图像的路径。
  更多的配置选项参考https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output进行自定义配置。

输出PDF文档

本地输出PDF文档

进入到本地MindSpore推理教程源文件inference目录下，执行以下命令生成PDF文档：

$ make latexpdf

输出完成后，会在当前目录下生成build_zh_cn目录，且生成的PDF文档位置为./build_zh_cn/latex/mindspore.pdf（输出的PDF文件已上传为附件）。

使用Docker输出PDF文档

进入到本地MindSpore推理教程源文件inference目录下，执行以下命令启动Sphinx容器，生成PDF文档：

$ docker run --rm -v {mindspore_inference_tutorial_path}:/docs sphinxdoc/sphinx-latexpdf make latexpdf

• 其中mindspore_inference_tutorial_path为本地MindSpore推理教程源文件目录的路径。

输出完成后，会在当前目录下生成build_zh_cn目录，且生成的PDF文档位置为./build_zh_cn/latex/mindspore.pdf。

注意事项

• 需要从源文件中去除引入了视频相关的MarkDown文档；
• 需要从源文件中去除引入了JIF格式图片的MarkDown文档；

结语

Sphinx作为优秀的技术文档输出的开源工具，用户可以方便的利用其输出多种格式的文档，但打铁还需自身硬，如何创建高质量的技术文档源文件才是才是技术人员最应该关心的，例如内容要抓住重点、贴切用户、易懂，引用的相关图片要合理，文档版本要随着产品迭代更新。高质量的技术文档，加上流行易用的文档解析工具，一定能给用户带来最好的体验。

来源 https://zhuanlan.zhihu.com/p/393688543