【转】 文档与笔记利器 reStructuredText 和 Sphinx

关于制作文档和笔记这种事，我已经纠结了很久，网上解决方案也一大推，我试过几样，ScrapBook 和 Zotero，编辑不太方便，同步麻烦。Google Note 过于格式简单，现在也不更新了，Google Docs又有点杀鸡用牛刀。还有传得很神奇的 Evernote 跟 Onenote，我压根没兴趣去用。

因为我的笔记大多都是自己写出来，整理出来的，就是精简成自己能看得懂的几段文字而已。我的要求无非这几样：主要是纯文本、工具开源、能同步和备份。

选择纯文本保存，我需要一个预定义格式，让笔记看起来有模有样，编辑器还能有简单代码高亮的，于是我在这个轻量级标记语言的维基页面观望好久。

Wiki也是一种不错方案，但是要搭服务器，不用服务器的也免不了各种配置，各种wiki系统的格式也不同。又研究了reStructuredText，发现阅读性非常好，能转换的格式也非常多。

vim就默认支持代码高亮了（rst扩展名），也能通过rst2html命令转换成的html，但是样式不太理想，我想应该有更漂亮的html生成器。于是我发现Sphinx这个工具，又当我发现其实这就是Python官方文档解决方案后。

我就做出最后决定了这一组合，reStructuredText作为标记语言，Sphinx作为生成工具。

预览

先来看看reStructuredText格式在vim的效果

生成html效果，就是python风格！

使用

只需安装python和sphinx即可。 安装python-sphinx这个包即可，自动解决依赖了，如果追新，则可以通过pypi来安装（也就是easy_install命令啦，不过要手动安装几个依赖库）。

安装后，应该会有sphinx-quickstart这个命令了。先新建一个空目录，这个目录会放置你的笔记

muzuiget:~$ mkdir note muzuiget:~$ cd note/ muzuiget:~/note$ sphinx-quickstart

会问你N个问题，一般来说，只需要填四个地方，其余的都直接回车就行了

1. Project name: Muzuiget Note
2. Author name(s): muzuiget
3. Project version: 1
4. Project release [1]: 1

加粗的是我填的，最后的两个发布号跟先跟版本号一样就行了，这个可以以后再改的。然后这个目录的内容就是这样

muzuiget:~/note$ tree . . |-- _build |-- conf.py |-- index.rst |-- make.bat |-- Makefile |-- _static `-- _templates 3 directories, 4 files

然后你可以用文本编辑器打开 index.rst 这个文件，如果用vim，就发现有代码高亮啦。暂时不用改什么，接着运行

muzuiget:~/note$ make html

然后用浏览器打开 _build/html/index.html 你会看到，舒服漂亮的python式文档出现鸟。

添加内容

当然现在什么内容也没有，现在你就可以向 index.rst 添加内容就行了。 至于reStructuredText的语法，reStructuredText、Sphinx、Python都有简单的教程

1. reStructuredText A ReStructuredText Primer
2. Sphinx reStructuredText Primer
3. Python reStructuredText Primer

这几个链接的html本身就是reStructuredText写出来的，比如第一个链接的源代码，另存到为 quickstart.rst，放到 index.rst 的统一目录下。然后修改 index.rst，就加一行

.. toctree:: :maxdepth: 2 quickstart.rst

注意“quickstart.rst”中的“q”和“ :maxdepth: 2”的冒号在同一列，保存，然后重新

muzuiget:~/note$ make html

再次刷新 _build/html/index.html，你就看到新的内容了，很简单吧。除了html外，sphinx也支持其它格式，直接运行make就能看到参数了。

ReStructuredText资料

下一步问题就是学习reStructuredText来编写规范的文档和笔记了，reStructuredText官方有个快速参考。而可供参考的实际例子更加多了，Sphinx的文档和Python文档就是非常规范了，页面旁边有个“Show Source”链接，还不够，Sphinx上还有个列表。

其实之前的sphinx-quickstart这个命令主要是创建了了 conf.py 这个文件，里面就是输出html或其它格式的配置，可以参考Sphinx文档来修改，定制性相当得高，还内置几种主题。这个方面还大家慢慢研究吧。

同步

对了，如何同步呢？还用多想，直接把笔记文件夹扔到Dropbox得了，就这么简单。在Bitbucket搭个私有仓库也行。