文档与笔记利器 reStructuredText 和 Sphinx

28 Jun
2011
# 作者: 投稿/转载 / / 本文采用CC BY-NC-SA 2.5协议授权,转载请注明本文链接

本文转载自七星庐 [ 原文:文档与笔记利器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个问题,一般来说,只需要填四个地方,其余的都直接回车就行了

  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搭个私有仓库也行。

加入我们 / 来 Wow!Ubuntu 问答社区参与更多讨论

21 Responses to 文档与笔记利器 reStructuredText 和 Sphinx

Avatar

lds

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 28th, 2011 at 10:56 am

不错的工具

Avatar

Juli

Firefox 4.0 Firefox 4.0 Windows 7 x64 Edition Windows 7 x64 Edition

June 28th, 2011 at 11:57 am

Avatar

Eua

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 28th, 2011 at 4:08 pm

bu cuo!

Avatar

fanhe

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 28th, 2011 at 5:07 pm

用vimwiki,只希望vimwiki功能更强大些.

Avatar

fanhe

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 28th, 2011 at 5:08 pm

vim的orgmode的插件有人做了出来了,就是不知道做到什么程度.

Avatar

鸟斑免

Firefox 5.0 Firefox 5.0 GNU/Linux x64 GNU/Linux x64

June 28th, 2011 at 5:56 pm

个人用的话,tiddlywiki不错的,不用server,很酷:http://www.tiddlywiki.com/

Avatar

owwbu

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 28th, 2011 at 8:04 pm

用zim的飘过,虽然页面不怎么美观,不过整理方便,还可以插入公式(如果安装了latex的话)。

Avatar

子非鱼

Maxthon 3.0 Maxthon 3.0 Windows 7 Windows 7

June 28th, 2011 at 11:50 pm

QuickFox Notes,火狐扩展,笔记可以跟书签一起同步。

Avatar

yc

Firefox 5.0 Firefox 5.0 Windows 7 Windows 7

June 29th, 2011 at 12:41 am

原来大家的评论中推荐的工具有时候比博主推荐的还要好用 :0

Avatar

kk

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

June 29th, 2011 at 1:08 am

那个python到底是干什么的?

Avatar

luc

Opera 11.50 Opera 11.50 GNU/Linux x64 GNU/Linux x64

June 29th, 2011 at 2:11 am

学习了,非常感谢。

Avatar

Steve

Pale Moon 5.0 Pale Moon 5.0 Windows XP Windows XP

June 29th, 2011 at 9:35 am

留言里Firefox5的普及率好高。用Vimwiki的飘过。

Avatar

tolbKni

Firefox 4.0 Firefox 4.0 GNU/Linux x64 GNU/Linux x64

June 29th, 2011 at 11:33 am

The archive and comments are wonderful!

Avatar

易邈之

Firefox 5.0 Firefox 5.0 GNU/Linux GNU/Linux

July 5th, 2011 at 6:50 pm

似乎挺麻烦的,Firefox5确实占了多数啊,再添一个。

Avatar

OpenBilly

Google Chrome 14.0.803.0 Google Chrome 14.0.803.0 GNU/Linux GNU/Linux

July 7th, 2011 at 9:05 pm

vimwiki是好东西呀。

Avatar

alswl

Google Chrome 13.0.782.220 Google Chrome 13.0.782.220 Windows 7 Windows 7

September 16th, 2011 at 4:44 pm

最近正在学习Sphinx,感谢分享
这里有一个同样不错的中文教程 http://readthedocs.org/docs/wyatts-docs/en/latest/text/rst_sphinx/

Avatar

amure

Firefox 6.0.2 Firefox 6.0.2 Windows XP Windows XP

September 17th, 2011 at 5:05 pm

没看明白 先标记

Avatar

nix

Safari 4.0.5 Safari 4.0.5 iPhone iOS 4.1 iPhone iOS 4.1

October 21st, 2011 at 1:19 pm

这个礼拜试试看,用来制作电子书如何?有格式导出HTML再KindleGen生成应该很方便。

Google Chrome 23.0.1271.101 Google Chrome 23.0.1271.101

amoblin Reply:

@nix, mac用户可以试试这个:https://code.google.com/p/markbook/

Avatar

使用Git和你喜欢的编辑器在Github上免费写博客 » 工大九网软件

WordPress 3.1 WordPress 3.1

September 11th, 2012 at 2:50 pm

[...] 九网软件关注小巧,有趣和边缘的软件和互联网应用 系统与普通编程网络图文音频趣味分类与归档追随我心工大八网← 校园网的孩子们,离开锐捷奔向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 . 我是个代码高亮控~)模板 和评论系统 (想要个个性点的模板,就要自己做喽)  [...]

Avatar

使用Git和你喜欢的编辑器在Github上免费写博客 » 工大九网软件

WordPress 3.1 WordPress 3.1

September 11th, 2012 at 2:51 pm

[...] 九网软件关注小巧,有趣和边缘的软件和互联网应用 系统与普通编程网络图文音频趣味分类与归档追随我心工大八网← 校园网的孩子们,离开锐捷奔向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 . 我是个代码高亮控~)模板 和评论系统 (想要个个性点的模板,就要自己做喽)  [...]

top