forked from EngineX-Cambricon/enginex-mlu370-vllm
91 lines
4.7 KiB
ReStructuredText
91 lines
4.7 KiB
ReStructuredText
使用说明
|
||
=============================
|
||
|
||
重要文件及文件夹说明
|
||
-----------------------------
|
||
|
||
**注意：**
|
||
|
||
工程下载后的所有内容，都不能删除，否则会造成工程编译失败。
|
||
|
||
* 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文件，检查最终效果。
|