使用restructedtext编写xresloader文档
离上一次写Blog过了好久啦。这次拖这么长时间主要是因为最近学习了一个新的文本标记语言 -- ReStructuredText 。并且重新整理了Excel导表工具-xresloader工具集的文档，写文档真是好废好废时间啊。
好多项目用ReStructuredText来写文档来着，比如cmake，再比如python。然后现在有比较容易上手的readthedocs来托管文档，和github的集成也还不错。所以我打算把一些项目的文档也迁移上去。毕竟 README.md 还是弱了些。
其实ReStructuredText也支持 Markdown 。但是使用 Markdown 写文档还是略麻烦，特别是涉及跨文档引用和多行表格的时候，而且 Markdown 各个平台的组件和扩展还都不一样，没有统一标准。在这些方面ReStructuredText就强大多了。不过这也是有代价的，那就是ReStructuredText的语法规则比 Markdown 复杂得多。
其实ReStructuredText很多语法规则和Markdown很想，像什么列表呀、加粗、斜体、标题啥的。不过ReStructuredText的制表，得用ascii画个表格，比较蛋疼。特别是对于大多数中文字体并不是等宽字体，源码看起来就很是诡异。所以我干脆用了[Noto][9]字体的中文等宽字体来显示，这下总算是对齐了。不过[Noto][9]的中文等宽字体的英文显示看起来很是怪异。因为它保证是中文的一半宽度。
ReStructuredText的跨文档引用和锚点是非常的方便。直接 :ref: 名字就行了。插入图片比较麻烦点，不过对于要自定义属性的话看起来就比 Markdown 的一大坨要好看的多。
ReStructuredText的官方生成工具是sphinx。sphinx还能自己指定主题，分析目录，生成静态搜索索引。这个 静态搜索索引 真的是非常实用，这样生成的文档也有搜索功能了。
我现在也只是初步入门，所以拿了xresloader来练手。拿xresloader当小白鼠的原因是对之前的文档不满意，对新手上手来说还很不明晰。而且xresloader的流程比较多，也比较适合多文档的结构。也是为了新手能快速上手，整理并撰写了 Quick Stark 和最简化sample（原来仓库里的sample是全功能sample，比较复杂）。然后就是对现有文档进一步整理归档和细节补充。现在应该是比较容易上手了，但是流程复杂它的 Quick Stark 仍然并不是很 Quick 。
目前主要还是用户文档，开发文档后面有兴趣再写吧。
xresloader项目地址： https://github.com/xresloader
xresloader文档地址： https://xresloader.atframe.work
Last updated