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

2022-03-21 00:00:00 文档 生成 安装 输出 源文件

转载地址：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

相关文章