Posts Tagged ‘Sphinx

本文转载自七星庐 [ 原文:文档与笔记利器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 [...]


top