1 背景

近期在学习torchtext相关内容，但是当前网络上相关的中文文档较少，一些博文描述的不是很详细，pytorch官方也打不开，于是在github下载了源码，看看github有没有相关的官方文档。对于一些github上的项目，我们通常看到的readme是md形式的，然而下载torchtext之后，发现并没有readme.md文件，到是有一个readme.rst的文件，并且能够在github上完美的展示。查阅资料有发现，rst文件也是一种标记文本，与md类似，其全称是：reStructuredText，更多关于rst信息可参考reStructuredText(rst)快速入门语法说明

rst文件是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

2 将RST文档转标准可视化文档

如何将python项目中，RST文档转成可视化文档呢？本文参考RST文件打开，结合torchtext github项目演示如下。

演示环境：window10， python3.7

2.1 文件结构介绍

当前项目解压后，项目结构文件如下（可能由于项目版本更新文件结构略有不同）：

根据文件路径，顾名思义项目的文档在docs文件夹下，进入后则有：

项目的具体文档内容在source文件夹中，进入查看有：

这时就可以看到很多以.rst结尾相关的官方说明文档，_static文件夹中的内容是rst经过转后成html所需的静态文件，如图片，css样式等。

回过头看docs文件夹下的其他文件，其中make.bat和makefile文件应该是不同系统中生成可视化文档的命令，在windows系统中点击make.bat没啥效果，脚本中的内容具体如何执行，由于我不是很擅长，这里就抛砖引玉，下面我会使用其他方式处理。至于requirements.txt文件是编译所需要一些要求，需要安装了sphinx和pytorch的样式包pytorch_sphinx_theme。

2.2 开始编译

在配置好所需环境后（该文档还需要有pytorch环境），下面使用相关编译命令对文档进行编译，命令如下：

sphinx-build -b html source build

其中参数释义如下：

• -b 即编译，后接编译后的结果 html，即将rst文档编译成html格式数据
• source 即包含rst文件的文件夹
• build 是编译后html文件存放的路径

编译过程如下：

由于无法连接pytorch官网，所以一些数据无法请求过来。最后编译的结果就在docs文件夹的build目录下：

打开index.html文件得到如下结果：

很多数据与官网文档样式相同，也勉强可看。

3 总结

总得来说，本文也是抛砖引玉了，解决了基本问题，希望能够帮助需要的人，以飨读者。