文档与笔记利器reStructuredText和Sphinx

标签: 软件介绍 | 发表时间:2011-06-27 23:47 | 作者:muzuiget Wick
出处:http://qixinglu.com

关于制作文档和笔记这种事,我已经纠结了很久,网上解决方案也一大推,我试过几样,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搭个私有仓库也行。

相关 [文档 笔记 restructuredtext] 推荐:

文档与笔记利器reStructuredText和Sphinx

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

文档与笔记利器 reStructuredText 和 Sphinx

- timebug - Wow! Ubuntu
本文转载自七星庐 [ 原文:文档与笔记利器reStructuredText和Sphinx / 作者 muzuiget ]. 关于制作文档和笔记这种事,我已经纠结了很久,网上解决方案也一大推,我试过几样,ScrapBook 和 Zotero,编辑不太方便,同步麻烦. Google Note 过于格式简单,现在也不更新了,Google Docs又有点杀鸡用牛刀.

淺談 reStructuredText 與 Sphinx

- khsing - Blog.XDite.net
但因為最近非常忙碌,所以在這裡只能淺談,請見諒. 「 第一次學 Rails 就上手 」2011/8 月的版本包含了 PDF 版本以及 EPUB 版. 這次的版本不是改寫,而是「重新排版」. 這份書的初稿是用 Markdown 謄寫手排. 而完稿則是用 Mac 上的軟體「Pages」手排. (你看,出書門檻不高吧 XD).

笔记

- 毛毛 - 游戏人生
我关于写代码的一些琐碎的看法. 之前没有把 Paul Graham 的 <黑客与画家> 一书读完, 上周就从同事那里把书带回家, 也一直没读, 到这周才有时间读完. 很久没有更新了 (一看时间, 整整 5 个月), 顺便把这篇写了几个月的感想放出来.. 这本书前面 8 章讲述的内容, 大多是我并不太感兴趣的, 比如财富, 比如创业.

Textmate笔记

- Sean Lee - Reborn
过去在Windows上还真的没有怎么太在意文本编辑器(也跟自己不是职业程序员有点关系吧. ),近来常在Mac上使用Textmate,真觉得一款好的文本编辑器实在非常必要. Textmate售价$58,很多人觉得贵,不过它真的不错. 为Finder加上“Open in textmate”按钮. 作者Henrik的主页上有详细的介绍.

OSX 笔记

- - C++博客-首页原创精华区
在vbox中安装10.7的方法:. 首先使用OS_X_Lion.iso.torrent下载操作系统的iso文件. 直接使用OS_X_Lion.iso安装,安装完之后使用HJMac.iso进行启动. 在win7 64bit上通过,但是在linux上没有通过. 升级,可以把10.7升级为10.7.4,方法是去苹果官方 http://support.apple.com/downloads 网站下载:.

笔记--redis

- - 移动开发 - ITeye博客
接着准备面试内容,今天学习了下redis,继续我的笔记加深印象. 1.为什么要使用redis.  答:主要是 性能和 并发两个方面,另外redis也可以做分布式锁和消息队列等其他功能. 但是如果只是为了分布式锁这些其他功能,完全还有其他中间件(如zookpeer等)代替,并不是非要使用redis.

云笔记:跨平台笔记服务

- one dollar - 天涯海阁-Web2.0Share
云笔记是一款跨平台的笔记服务,目前提供了Android、iPhone、iPad客户端(FIT写字板、FIT Paper). 最早知道云笔记也是因为一直使用FIT写字板,发现FIT写字板更新之后支持了云同步,才发现了云笔记. 云笔记是新点科技旗下的产品,相信Mac用户都会知道FIT输入法,Mac和iOS上面很棒的输入法应用.

小岛笔记 Day1

- Qian - 吃素菜,彼此相爱。
去巴厘岛之前,我们对旅行进行了明确分工,我负责研究攻略. 我特意买了09年版的孤独星球,像小学生一样注了注,贴了几溜彩色便签. 临行前,我被各种词条式的信息膨胀着,能在10秒内,标出7座海神庙9座指示方位神庙的地图方位. 状态好时,能说出哪家餐馆在哪页地图的横几格竖几格. 包哥最怕坐飞机,又贵看着又不安全的事儿,有悖他的人生信条.

笔记本爱经

- Yuheng Kuang - 煎蛋
oioi:sein已经回家过年 :|. 名为KamaSutra(爱经)Lap,看看你与笔记本最亲近的姿势会是怎样 :) link. 老实说大部分时间,这玩意并没有让我感觉舒服. © oioi for 煎蛋 / 20回复 / 投稿 / 图片托管于又拍网. geek:极客2011日历(图集). 数码看新鲜:Dell 旋转屏幕笔记本.