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

转载地址：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推理教程的源文件下载到本地后，进入到该目录下:

   inference
   ├── Makefile
   ├── requirements.txt
   ├── source_en
   │   ├── conf.py
   │   ├── index.rst
   │   ├── multi_platform_inference_ascend_310.md
   │   ├── multi_platform_inference_ascend_910.md
   │   ├── multi_platform_inference_cpu.md
   │   ├── multi_platform_inference_gpu.md
   │   ├── multi_platform_inference.md
   │   ├── serving.md
   │   └── _static
   └── source_zh_cn
      ├── conf.py
      ├── index.rst
      ├── multi_platform_inference_ascend_310.md
      ├── multi_platform_inference_ascend_910.md
      ├── multi_platform_inference_cpu.md
      ├── multi_platform_inference_gpu.md
      ├── multi_platform_inference.md
      ├── serving.md
      └── _static
   

   执行以下命令安装sphinx：

   $ pip install -r requirements.txt
   

2. 安装xelatex。

   使用apt管理器执行以下命令安装xelatex引擎（整体约为3G大小，用时较久，请耐心等待）：

   $ sudo apt-get install texlive-lang-chinese \
                          graphviz \
                          imagemagick \
                          make \
                          latexmk \
                          lmodern \
                          texlive-latex-recommended \
                          texlive-latex-extra \
                          texlive-fonts-recommended \
                          texlive-fonts-extra \
                          texlive-lang-cjk \
                          texlive-luatex \
                          texlive-xetex \
                          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, 在末尾添加如下所示代码：

   latex_engine = 'xelatex'
   latex_use_xindy = False
   latex_elements = {
       'preamble': '\\usepackage[UTF8]{ctex}\n',
       'papersize': 'a4paper',
       'pointsize': '10pt',
   }
   latex_toplevel_sectioning = None
   latex_domain_indices = True
   latex_show_pagerefs = False
   latex_logo = '{logo_path}'
   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作为优秀的技术文档输出的开源工具，用户可以方便的利用其输出多种格式的文档，但打铁还需自身硬，如何创建高质量的技术文档源文件才是才是技术人员最应该关心的，例如内容要抓住重点、贴切用户、易懂，引用的相关图片要合理，文档版本要随着产品迭代更新。高质量的技术文档，加上流行易用的文档解析工具，一定能给用户带来最好的体验。