关于制作文档和笔记这种事,我已经纠结了很久,网上解决方案也一大推,我试过几样,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 和 Sphinx的更多相关文章

  1. Keras 文档阅读笔记(不定期更新)

    目录 Keras 文档阅读笔记(不定期更新) 模型 Sequential 模型方法 Model 类(函数式 API) 方法 层 关于 Keras 网络层 核心层 卷积层 池化层 循环层 融合层 高级激 ...

  2. rocksdb wiki文档阅读笔记

    由于是英文文档,不做笔记过一阵就忘了,现在把关键点记录到这,开发的时候使用. 具体wiki地址:https://github.com/facebook/rocksdb/wiki 1)Column Fa ...

  3. [BI项目记]-配置Sharepoint2013支持文档版本管理笔记

    做开发或者做方案,写文档是很重要的一个工作,我们经常需要知道文档被修改的次数,谁在什么时间修改的文档,以及在某一个版本中,都修改了哪些内容,以及不同版本的文档之间有什么差别. 如何对文档进行版本管理, ...

  4. [BI项目记]-文档版本管理笔记

    代码的版本管理程序员们有专门的工具,那么作为项目管理人员如何进行文档版本的管理呢,此篇介绍如何通过SharePoint进行文档版本管理. 在没有SharePoint的时代我们如何管理版本呢?通常我们会 ...

  5. 通过程序校验xml文档学习笔记

    校验xml文档,可以通过程序来校验,利用一段js代码即可. 各行代码的含义已经写出,运行这个html文件,检验如下xml代码: 结果如下: 如果xml文档出现错误: 结果如下: 其中,obj.asyn ...

  6. appium python andiroid自动化文档整理笔记。

    利用一天时间去整理appium for android文档.传送门 利用业余时间自己翻阅资料,google.百度等去查找,费劲一番功夫,最后终于成行了这篇文档. 也是作者对最近自己的学习的一个总结吧, ...

  7. JDK8帮助文档生成-笔记

    JDK8 出来了,以前习惯了使用.CHM文件来查看API,现在想也这样,这里自己制作了一下,记录一下. 1.需要的工具: ①JD2CHM;②API文档③HTMLlHelper 遇到的问题主要是不知道去 ...

  8. Resin文档阅读笔记

    阅读文档对应的版本为Resin4.0,且基本只关注Standard版本的功能. 1.Resin可以注册为服务: To install the service, use C:/> resin-3. ...

  9. KVM内核文档阅读笔记

    KVM在内核中有丰富的文档,位置在Documentation/virtual/kvm/. 00-INDEX:整个目录的索引及介绍文档. api.txt:KVM用户空间API,所谓的API主要是通过io ...

随机推荐

  1. el-input监听不了回车事件

    vue使用element-ui的el-input监听不了回车事件,原因应该是element-ui自身封装了一层input标签之后,把原来的事件隐藏了,所以如下代码运行是无响应的: <el-inp ...

  2. quartz源码分析——执行引擎和线程模型

    title: quartz源码分析--执行引擎和线程模型 date: 2017-09-09 23:14:48 categories: quartz tags: [quartz, 源码分析] --- - ...

  3. Project 8:利用递归算法求最大值

    目标:用递归算法实现求一个数组中的最大元素. 样例输入 5 1 4 2 5 3 样例输出 5 #include <stdio.h> int max(int *,int); int main ...

  4. YYHS-怎样更有力气

    题目描述 OI大师抖儿在夺得银牌之后,顺利保送pku.这一天,抖儿问长者:"我虽然已经保送了,但我的志向是为国家健康工作五十年.请问我应该怎样变得更有力气?"  长者回答:&quo ...

  5. 201521123093 java 第六周学习总结

    1. 本周学习总结 1.1 面向对象学习暂告一段落,请使用思维导图,以封装.继承.多态为核心概念画一张思维导图,对面向对象思想进行一个总结. 注1:关键词与内容不求多,但概念之间的联系要清晰,内容覆盖 ...

  6. 201521123093 java 第四周学习总结

    1.平面作业 1.1 尝试使用思维导图总结有关继承的知识点. 1.2 使用常规方法总结其他上课内容. 答:1.类与方法的注释 2.super关键字代表的是父类,super.方法表示调用的是父类 2. ...

  7. 201521123005 《Java程序设计》 第十周学习总结

    1. 本周学习总结 1.1 以你喜欢的方式(思维导图或其他)归纳总结异常与多线程相关内容. 2. 书面作业 本次PTA作业题集异常.多线程 1.finally 题目4-2 1.1 截图你的提交结果(出 ...

  8. 201521145048《java程序与设计》第9周学习总结

    1. 本周学习总结 1.1 以你喜欢的方式(思维导图或其他)归纳总结异常相关内容. 2. 书面作业 本次PTA作业题集异常 Q1.常用异常 题目5-1 1.1 截图你的提交结果(出现学号) 1.2 自 ...

  9. AIX盘rw_timeout值过小导致IO ERROR

    刚下班没多久,接收到告警提示数据库的数据文件异常,且同时收到主机硬盘的IO ERROR告警 该数据库服务器为AIX+oracle 9i环境,登录主机验证关键日志告警 发现确实在18点48分有磁盘IO的 ...

  10. Windows下chm转换为html的超简单方法

    摘要:通过调用Windows命令,将chm 文件转换为html 文件 概述:很多程序员朋友都会遇到这样的问题,看一个离线版的帮助文档(chm文件),总会产生一个索引文件(该文件的chw文件), 而且有 ...