Search
文档与笔记利器 reStructuredText 和 Sphinx
28 六2011
本文转载自七星庐 [ 原文：文档与笔记利器reStructuredText和Sphinx / 作者 muzuiget ]
关于制作文档和笔记这种事，我已经纠结了很久，网上解决方案也一大推，我试过几样，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个问题，一般来说，只需要填四个地方，其余的都直接回车就行了
- Project name: Muzuiget Note
- Author name(s): muzuiget
- Project version: 1
- 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都有简单的教程
- reStructuredText A ReStructuredText Primer
- Sphinx reStructuredText Primer
- 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搭个私有仓库也行。
- 作者: 投稿/转载
- Post Time: 2011/06/28 10:33:04 上午
- In: 技巧
- Tags: reStructuredText, Sphinx
21 Responses to 文档与笔记利器 reStructuredText 和 Sphinx
lds
六月 28th, 2011 at 10:56 上午
不错的工具
Juli
六月 28th, 2011 at 11:57 上午
http://code.google.com/p/zoeeydoc/
Eua
六月 28th, 2011 at 4:08 下午
bu cuo!
fanhe
六月 28th, 2011 at 5:07 下午
用vimwiki,只希望vimwiki功能更强大些.
fanhe
六月 28th, 2011 at 5:08 下午
vim的orgmode的插件有人做了出来了,就是不知道做到什么程度.
鸟斑免
六月 28th, 2011 at 5:56 下午
个人用的话，tiddlywiki不错的，不用server，很酷：http://www.tiddlywiki.com/
owwbu
六月 28th, 2011 at 8:04 下午
用zim的飘过，虽然页面不怎么美观，不过整理方便，还可以插入公式（如果安装了latex的话）。
子非鱼
六月 28th, 2011 at 11:50 下午
QuickFox Notes，火狐扩展，笔记可以跟书签一起同步。
yc
六月 29th, 2011 at 12:41 上午
原来大家的评论中推荐的工具有时候比博主推荐的还要好用 ：0
kk
六月 29th, 2011 at 1:08 上午
那个python到底是干什么的？
luc
六月 29th, 2011 at 2:11 上午
学习了，非常感谢。
Steve
六月 29th, 2011 at 9:35 上午
留言里Firefox5的普及率好高。用Vimwiki的飘过。
tolbKni
六月 29th, 2011 at 11:33 上午
The archive and comments are wonderful!
易邈之
七月 5th, 2011 at 6:50 下午
似乎挺麻烦的，Firefox5确实占了多数啊，再添一个。
OpenBilly
七月 7th, 2011 at 9:05 下午
vimwiki是好东西呀。
alswl
九月 16th, 2011 at 4:44 下午
最近正在学习Sphinx，感谢分享
这里有一个同样不错的中文教程 http://readthedocs.org/docs/wyatts-docs/en/latest/text/rst_sphinx/
amure
九月 17th, 2011 at 5:05 下午
没看明白 先标记
nix
十月 21st, 2011 at 1:19 下午
这个礼拜试试看，用来制作电子书如何？有格式导出HTML再KindleGen生成应该很方便。
amoblin Reply:
一月 9th, 2013 at 4:56 下午
@nix, mac用户可以试试这个：https://code.google.com/p/markbook/
使用Git和你喜欢的编辑器在Github上免费写博客 » 工大九网软件
九月 11th, 2012 at 2:50 下午
[…] 九网软件关注小巧,有趣和边缘的软件和互联网应用 系统与普通编程网络图文音频趣味分类与归档追随我心工大八网← 校园网的孩子们,离开锐捷奔向MentoHust吧回到顶部使用Git和你喜欢的编辑器在Github上免费写博客九 11作者 hit9 属于 网络本文将讨论一个十分Geek又免费的写Blog的方案 .Github 提供了一项服务叫做Github Pages (为开发者建立自己或自己的项目的页面的服务). 1.基本的思路 每个Github用户可以建立一个”特殊”名字的repo(比如我的用户名是hit9,这个源的名字就是hit9.github.com). 这个项目下的文件可以通过http访问到(比如我的,访问http://hit9.github.com). 就是说, Github为你提供了一个免费的web空间.这样就可以搭建一个本地的项目, 我们本地用自己喜爱的编辑器在本地写blog,然后用git更新这个项目来更新互联网上的博客.基本思路: Github Page免费空间+Git+你的编辑器(vim/emacs 等)+速写标记语言(markdown等)+社会化评论2.支持Github Pages支持静态的html和jeklly (用来部署静态网页的工具)框架. 3. 可选的工具当然,除去编辑器不谈,我们首先谈的是书写blog的语言.使用标记语言我们当然不能使用html去写博客了.建议的是,采用流行的标记语言markdown . 当然还可以选择liquid 和著名的 vimwiki ,还有reStructuredText使用静态页面部署工具我们需要一个工具来组织博客.这种工具很多很多~(选择一个作为自己的即可)不完全列举: 1. jekyll (每一个离开wordpress投奔到jekyll的bloger都有一颗长期被wordpress蹂躏的心)教程: http://jekyllbootstrap.com/ (感觉这个教程非常人性化.)采用的标记语言:markdownjekyllbootstrap还提供了许多博客皮肤.注: jekyll允许你从wordpress ,Drupal 6.1, Tumblr等转到jekyll, 提供了转型的方案. PS: 这个模式估计是最流行的static web 解决方案(Github Pages+markdown+jekyll) 2.octopress (如果说markdown速写成文,那么octopress速写成书)教程:官网doc 建议的中文教程采用的标记语言:markdownoctopress的默认模板就很漂亮.octopress定制简单, 你可以实现代码高亮, 标签, 评论等功能(自己折腾吧~~ 折腾好了才会顺手,才会喜欢)国内用这个的很多,所以文档会很齐全.3. vimwiki (想想用vim写代码有多爽,用vimwiki写博客就有多爽)教程:丘迟采用的标记语言:vimwikivimwiki的火应该是vimer们烧起来的. 也许还有人没听过vimwiki. vimwiki采用的标记语言不是markdown,而是自己独有的语法(这降低了它的流行度,也增加了学习成本)它也有模板定制功能, 也可以实现代码高亮.vimwiki本来是用来写wiki的,但是用它来快速生成html也可以用来写博客.我的博客采用的vimwiki.以下不再详细说明~4.toto the 10 second blog-engine for hackers5. 以上都是Ruby世界的. Python的列表见这里 6.reStructuredText + Sphinx + github pages (Sphinx将reStructuredText 文件转换成各种格式)使用社会化评论( 无评论,不博客) 目前社会化的评论让评论无处不在,安装和使用也十分方便,只要在模板中插入一段js代码,就可以使用社会化评论框.数据也不用自己管理.比较知名的社会化评论工具: Disqus . 国内比较知名的有 多说 4.需要折腾什么?想不到如此Geek式的写博客的方式里面也是百家争鸣的架势啊. 这个写博客的模式带着浓浓的code 味道, 很适合程序猿们使用.hit9认为选择使用Github写博客的方式需要去折腾这么几个事情:你喜欢的编辑器(用自己的编辑器写博客是个很惬意的事情,所以编辑器要处理好对markdown等你所使用的标记语言的高亮和补全)代码高亮的支持( 基本上有两类方案:使用python 或者使用js .推荐pygments, SyntaxHighlighter . 我是个代码高亮控~)模板 和评论系统 (想要个个性点的模板,就要自己做喽) […]
使用Git和你喜欢的编辑器在Github上免费写博客 » 工大九网软件
九月 11th, 2012 at 2:51 下午
[…] 九网软件关注小巧,有趣和边缘的软件和互联网应用 系统与普通编程网络图文音频趣味分类与归档追随我心工大八网← 校园网的孩子们,离开锐捷奔向MentoHust吧回到顶部使用Git和你喜欢的编辑器在Github上免费写博客九 11作者 hit9 属于 网络本文将讨论一个十分Geek又免费的写Blog的方案 .Github 提供了一项服务叫做Github Pages (为开发者建立自己或自己的项目的页面的服务). 1.基本的思路 每个Github用户可以建立一个”特殊”名字的repo(比如我的用户名是hit9,这个源的名字就是hit9.github.com). 这个项目下的文件可以通过http访问到(比如我的,访问http://hit9.github.com). 就是说, Github为你提供了一个免费的web空间.这样就可以搭建一个本地的项目, 我们本地用自己喜爱的编辑器在本地写blog,然后用git更新这个项目来更新互联网上的博客.基本思路: Github Page免费空间+Git+你的编辑器(vim/emacs 等)+速写标记语言(markdown等)+社会化评论2.支持Github Pages支持静态的html和jeklly (用来部署静态网页的工具)框架. 3. 可选的工具当然,除去编辑器不谈,我们首先谈的是书写blog的语言.使用标记语言我们当然不能使用html去写博客了.建议的是,采用流行的标记语言markdown . 当然还可以选择liquid 和著名的 vimwiki ,还有reStructuredText使用静态页面部署工具我们需要一个工具来组织博客.这种工具很多很多~(选择一个作为自己的即可)不完全列举: 1. jekyll (每一个离开wordpress投奔到jekyll的bloger都有一颗长期被wordpress蹂躏的心)教程: http://jekyllbootstrap.com/ (感觉这个教程非常人性化.)采用的标记语言:markdownjekyllbootstrap还提供了许多博客皮肤.注: jekyll允许你从wordpress ,Drupal 6.1, Tumblr等转到jekyll, 提供了转型的方案. PS: 这个模式估计是最流行的static web 解决方案(Github Pages+markdown+jekyll) 2.octopress (如果说markdown速写成文,那么octopress速写成书)教程:官网doc 建议的中文教程采用的标记语言:markdownoctopress的默认模板就很漂亮.octopress定制简单, 你可以实现代码高亮, 标签, 评论等功能(自己折腾吧~~ 折腾好了才会顺手,才会喜欢)国内用这个的很多,所以文档会很齐全.3. vimwiki (想想用vim写代码有多爽,用vimwiki写博客就有多爽)教程:丘迟采用的标记语言:vimwikivimwiki的火应该是vimer们烧起来的. 也许还有人没听过vimwiki. vimwiki采用的标记语言不是markdown,而是自己独有的语法(这降低了它的流行度,也增加了学习成本)它也有模板定制功能, 也可以实现代码高亮.vimwiki本来是用来写wiki的,但是用它来快速生成html也可以用来写博客.我的博客采用的vimwiki.以下不再详细说明~4.toto the 10 second blog-engine for hackers5. 以上都是Ruby世界的. Python的列表见这里 6.reStructuredText + Sphinx + github pages (Sphinx将reStructuredText 文件转换成各种格式)使用社会化评论( 无评论,不博客) 目前社会化的评论让评论无处不在,安装和使用也十分方便,只要在模板中插入一段js代码,就可以使用社会化评论框.数据也不用自己管理.比较知名的社会化评论工具: Disqus . 国内比较知名的有 多说 4.需要折腾什么?想不到如此Geek式的写博客的方式里面也是百家争鸣的架势啊. 这个写博客的模式带着浓浓的code 味道, 很适合程序猿们使用.hit9认为选择使用Github写博客的方式需要去折腾这么几个事情:你喜欢的编辑器(用自己的编辑器写博客是个很惬意的事情,所以编辑器要处理好对markdown等你所使用的标记语言的高亮和补全)代码高亮的支持( 基本上有两类方案:使用python 或者使用js .推荐pygments, SyntaxHighlighter . 我是个代码高亮控~)模板 和评论系统 (想要个个性点的模板,就要自己做喽) […]