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