专栏首页owent使用restructedtext编写xresloader文档

使用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字体的中文等宽字体来显示,这下总算是对齐了。不过Noto的中文等宽字体的英文显示看起来很是怪异。因为它保证是中文的一半宽度。

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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • libatbus的几个藏得很深的bug

    在写这篇文章前,我突然想到以前流行了一段时间的服务器面试题:当一个BUG只有几百万分之一的概率会出现,怎么办?这个问题在这个BUG里只是毛毛雨而已,因为这次的B...

    owent
  • Lua 挺好用的样子

    其实对于理解Javascipt的人来说,Lua也很容易理解,因为他们太多的地方相像了。

    owent
  • C++20 Coroutine 性能测试 (附带和libcopp/libco/libgo/goroutine/linux ucontext对比)

    之前写了 《协程框架(libcopp)v2优化、自适应栈池和同类库的Benchmark对比》 和 《C++20 Coroutine》 ,但是一直没写 C++20...

    owent
  • SDK开发经验之文档

    子勰
  • python打开音乐文件的实例方法

    砸漏
  • Lucene学习总结之一:全文检索的基本原理

    根据http://lucene.apache.org/java/docs/index.html定义:

    Hongten
  • Data Structures and Algorithms Basics(016):Greedy

    用户5473628
  • 从wrfout 提取站点数据

    数据准备是机器学习的基础,俗话说巧妇难为无米之炊,没有数据的机器学习就是耍流氓。

    zhangqibot
  • 剑指offer代码解析——面试题22栈的压入、弹出序列

    本题的详细分析过程均在代码的注释中: import java.util.Stack; /** * 题目:输入两个整数序列,第一个序列表示栈的压入顺序,请判断...

    大闲人柴毛毛
  • 浏览器的UI线程

    所有用于更新用户界面的操作都是由浏览器的UI线程来完成 UI线程维护一个队列,把每个要更新UI的操作都做为一个任务添加到队列中,然后等UI线程空闲时再按顺序进...

    dys

扫码关注云+社区

领取腾讯云代金券