离上一次写Blog过了好久啦。这次拖这么长时间主要是因为最近学习了一个新的文本标记语言 – ReStructuredText 。并且重新整理了Excel导表工具-xresloader工具集的文档,写文档真是好废好废时间啊。

好多项目用ReStructuredText来写文档来着,比如cmake,再比如python。然后现在有比较容易上手的readthedocs来托管文档,和github的集成也还不错。所以我打算把一些项目的文档也迁移上去。毕竟 README.md 还是弱了些。

其实ReStructuredText也支持 Markdown 。但是使用 Markdown 写文档还是略麻烦,特别是涉及跨文档引用和多行表格的时候,而且 Markdown 各个平台的组件和扩展还都不一样,没有统一标准。在这些方面ReStructuredText就强大多了。不过这也是有代价的,那就是ReStructuredText的语法规则比 Markdown 复杂得多。

其实ReStructuredText很多语法规则和Markdown很想,像什么列表呀、加粗、斜体、标题啥的。不过ReStructuredText的制表,得用ascii画个表格,比较蛋疼。特别是对于大多数中文字体并不是等宽字体,源码看起来就很是诡异。所以我干脆用了Noto字体的中文等宽字体来显示,这下总算是对齐了。不过Noto的中文等宽字体的英文显示看起来很是怪异。因为它保证是中文的一半宽度。

ReStructuredText的跨文档引用和锚点是非常的方便。直接 :ref: 名字就行了。插入图片比较麻烦点,不过对于要自定义属性的话看起来就比 Markdown 的一大坨要好看的多。

ReStructuredText的官方生成工具是sphinxsphinx还能自己指定主题,分析目录,生成静态搜索索引。这个 静态搜索索引 真的是非常实用,这样生成的文档也有搜索功能了。

我现在也只是初步入门,所以拿了xresloader来练手。拿xresloader当小白鼠的原因是对之前的文档不满意,对新手上手来说还很不明晰。而且xresloader的流程比较多,也比较适合多文档的结构。也是为了新手能快速上手,整理并撰写了 Quick Stark 和最简化sample(原来仓库里的sample是全功能sample,比较复杂)。然后就是对现有文档进一步整理归档和细节补充。现在应该是比较容易上手了,但是流程复杂它的 Quick Stark 仍然并不是很 Quick

目前主要还是用户文档,开发文档后面有兴趣再写吧。

xresloader项目地址: https://github.com/xresloader

xresloader文档地址: https://xresloader.atframe.work