enginex-mlu370-vllm/torch_mlu_ops-v1.3.2/docs/user_guide

使用说明
=============================

重要文件及文件夹说明
-----------------------------

**注意：**

  工程下载后的所有内容，都不能删除，否则会造成工程编译失败。

* source文件夹：保存rst源文件。所有新增的rst文件及文件夹务必都保存在source文件夹中，否则生成的文件将不包含新增内容。
* build文件夹：保存构建后的文件，该文件在执行make html和./makelatexpdf.sh后会自动生成。build及其子文件夹都是构建后自动生成，所以无需关注。

  - 执行make html生成html文件，保存在“build/html”文件夹中。
  - 执行./makelatexpdf.sh生成latex和pdf文件，保存在“build/latex”文件夹中。

* makelatexpdf.sh：核心编译脚本，生成latex和pdf文件。

  **注意：**

    下载工程后，请执行“chmod +x makelatexpdf.sh”命令修改该文件的权限，否则脚本无法执行。

* source/index.rst：核心索引文件，sphinx依据该文件生成文件的大纲目录。所有新增的rst文件都要添加到该文件中，否则生成的文档中将不包含新增内容。

文档写作约束
--------------------------------

**rst语法参考网址** ：http://www.pythondoc.com/sphinx/rest.html

rst文件为纯文本文件，因此可以使用vim、notepad++或者vscode等任何文本编辑器编写。其中vim天然支持rst，会对rst语法进行高亮显示。
vscode可以通过下载插件的方式实现rst语法高亮和实时预览，但是vscode对rst表格的兼容性不是很好。

**注意：**

  不管用哪种编辑器，都务必将tab设置为4个空格，否则格式可能会达不到预期，或者引入编译告警。尤其影响表格的编辑，因此务必将tab设置为4个空格。

* 文档编译服务器，工程可以下载到该服务器编写编译。目前只有该服务器搭建了文档编译环境，能够完成文档的编译。
* 所有新增内容，都务必放在“source”文件夹下，不能放在其它文件夹，避免工程编译失败，达不到预期效果。
* 一级大纲或者新建的独立模块建议新建文件夹，rst源文件都保存在新建文件夹下，以便工程有清晰的层级结构，方便维护。可以参考“preface”文件夹的构建。
* 文件目录深度最多为4级，超过4级不方便用户阅读。4个级别大纲的标识按以下顺序：

  1. 一级大纲标识：=；
  #. 二级大纲标识：-；
  #. 三级大纲标识：^;
  #. 四级大纲标识：~;

  举例如下：

  ::

    我是一级大纲举例
    ========================
    我是二级大纲举例
    ------------------------
    我是三级大纲举例
    ^^^^^^^^^^^^^^^^^^^^^^^^
    我是四级大纲举例
    ~~~~~~~~~~~~~~~~~~~~~~~~

使用举例
----------------------------------------

以新建“前言”章节为例，举例说明如何新增内容，新增内容后，如何编译生成html和pdf文件。下载的工程中“前言”章节已经添加完成，可以参考。

* 步骤一：通过ssh登陆文档编译服务器。
* 步骤二：在Torch-MLU-Ops仓库下载user_guide文件夹及其内容。
* 步骤三：执行命令“chmod +x makelatexpdf.sh”修改makelatexpdf.sh脚本的权限，避免无法编译。
* 步骤四：在“source”文件夹下，新建“preface”文件，保存前言相关的rst文件。
* 步骤五：在“preface”文件夹下，新建两个文件：preface.rst和index.rst。

  - preface.rst：用来保存前言相关内容
  - index.rst：用来保存"preface"文件夹下所有rst文件的索引。

  将preface.rst添加到index.rst。

  **说明**

    preface文件夹下新建index.rst是为了方便管理同一文件夹下的内容，这样在外层的主索引文件“index.rst”中只要添加该文件夹的index索引文件即可。

    也可以不新建index.rst，将preface文件夹下的文件一一添加到外层的主索引文件“index.rst”中。为了方便管理建议每个文件夹下都新建index.rst统一管理该文件夹下的索引。

* 步骤六：按照rst语法和文档写作约束编写preface.rst”文件。
* 步骤七：将“preface/index.rst”文件添加到外层的主索引文件“index.rst”中。
* 步骤八：执行“./makelatexpdf.sh”脚本生成pdf文件，保存在“build/latex”文件夹下。执行“make html”命令生成html文件，保存在“build/html”文件夹下。

  **注意：**

    在执行“./makelatexpdf.sh”或者“make html”过程中，要注意sphinx红色字体的“WARNING"告警，务必将告警清除，否则可能无法生成文件或者生成的文件无法达到预期。

经过以上步骤，“前言”章节添加成功，可以查看最终生成的pdf和html文件，检查最终效果。