python打开文件_【Python】RST文件打开——以torchtext官方github文档为例

文 | 菊子皮 (转载请注明出处) 作者B站：科皮子菊

1 背景

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

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

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

如何将python项目中，RST文档转成可视化文档呢？本文参考RST文件打开^[2]，结合torchtext^[3] 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 总结

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

参考资料

[1]

reStructuredText(rst)快速入门语法说明: https://www.jianshu.com/p/1885d5570b37

[2]

RST文件打开: https://blog.csdn.net/power0405hf/article/details/79110657

[3]

torchtext: https://github.com/pytorch/text

剑指Offer刷题集| Python基础

更多精彩文章

机器学习分类器性能标准(Accuracy、Precision、Recall、P-R曲线、F1等)你是否真的懂了？

不仅仅要会导别人的包也要会导自定义的包——Python导包总结！

回归树分析与sklearn决策树案例！

决策树算法——集成学习的基础！

如何用Python书写计算任一多变量函数任一点的偏导导数值？

一个绘制决策树的工具——graphviz，但你忽视了它的其他功能，如结构句法分析结果！

VSCode再添新功能——绘制流程图，来看看如何操作吧！

如何解决下载Github源码慢的问题

sklearn机器学习入门案例——使用k近邻算法进行鸢尾花分类

Python中的迭代器和生成器

最优化问题:拉格朗日乘子法、KKT条件以及对偶问题