1. 简介

写文档是开发人员日常工作中的一项重要内容，除了word之外，我更偏爱使用标记语言(Markup Language)。使用标记语言，可以利用简单、免费的文本编辑器(记事本，vim, emacs...）编写文档并设置格式，再生成html或pdf等格式，或者直接把编辑好的文件传到github或wiki上面 ，通过浏览器可以直接查看带有格式的文档。

目前标记语言主要有两种，Markdown和reStructuredText（简称reST)。该使用哪一种是一个见仁见智的选择，我在这里就不比较它们（包括其他标记语言）的优劣了，感兴趣的可以参考：

• 知乎：Org-mode、reST、 Markdown 各有什么优缺点？
• 维基百科（英文）：Lightweight markup language

对我个人来说，一开始尝试了一段时间的Markdown，由于工具不好用以及支持的格式不多的原因，转而使用reST，再配合sphinx，感觉好极了。

很多开源项目的文档就是用sphinx+reST做的，比如最近我正关注的hyperscan：http://01org.github.io/hyperscan/dev-reference/。大家可以点进去看一下生成的效果，它用的样式是Alabaster 0.7.6。