OfflineDoc: 离线文档生成器
作为一个程序员,每天的工作打交道最多的除了写代码,估计就是查文档了。mongodb 有个 update modifier 又忘记格式要求了,django 的 model 都有哪些 field 类型,都得查文档。要做到高效工作,不需要背下所有知识,只需要知道什么时候该用什么东西,去哪里找需要的东西。
去哪里查文档呢?很多情况下你不会去 google,因为你知道你要找的就在官方文档里。所以遇到一门新语言、一个新库,我推荐的学习方式就是把官方文档大致看一遍,这样 以后遇到问题大概就会知道官方文档里有没有这方面的资料。
官方文档是最全面权威的文档,一般都是在线 HTML 页面方式呈现。我很喜欢浏览 HTML 版本的文档:不需要额外软件或插件,只需要一个浏览器;图文并茂,而且大部分前端的还在文档中自带 demo。我经常沉浸在 python、django、angular.js、pymongo 的在线文档里,收获颇丰。
看起来很好。但是,在线文档有几个致命的缺点:
- 离线无法使用。这样你在无网络的环境下就没法查文档写代码了。
- 龟速网络导致查文档时间大部分浪费在等待网络 I/O 上了。不可忍。
- 大部分只提供最新版本文档,不提供历史文档。维护旧代码时查文档很痛苦。
由此出现了一些专门给程序员看的文档服务,如 http://devdocs.io/ 和 https://readthedocs.org/ 。似乎很不错,但是,这两个服务也有缺点:
devdocs.io:
- 按自己格式排版了文档。官方文档的排版和内容才是王道。
- 支持项目少,版本旧,增加项目困难。由于有一套排版,更新岂能不困难。
readthedocs.org:
- 只支持有 sphinx 编写的文档的项目
这两者都有一个致命的缺点:无法灵活添加自有项目(例如公司内部项目);无法添加诸如 amcharts 本身根本不提供文档生成方法的项目。
所以才有了 OfflineDoc 的诞生。OfflineDoc 的目标是用简单的方式去生成、定期更新离线文档,并解决上述难题。
OfflineDoc 支持的项目类型有:
- Git 项目
- SVN 项目
- 其它有 HTML 文档的任意项目
对 Git 和 SVN 项目,OfflineDoc 会取出源码,如果该项目有自身的文档生成方法(Sphinx、jekyl、make、Rake 等),会利用相应方式生成和官方一样的 HTML 文档;对其余不提供文档生成方法的流氓项目,只要其有在线 HTML 文档,就会使用 wget 镜像大法全部抓下来。
首先安装(推荐使用 virtualenv):
mkdir -p ~/envs
virtualenv ~/envs/od
source ~/envs/od/bin/activate
pip install offlinedoc
最终显示 "Successfully installed ..." 之类表示正确安装了。由于内置了二十多个常用项目,在生成它们的文档前需要安装一些库(以 ubuntu 为例):
- nodejs:
sudo apt-get install nodejs
。或者直接去官网下载最新版本。 - grunt 和 bower:
sudo npm install -g grunt-cli && sudo npm install bower -g
- 编译依赖包:
sudo apt-get install build-essential python-dev ruby1.9.1-dev git-core default-jre
- jekyll:
sudo gem install jekyll
安装好之后,在 shell 下输入 od.py
回车看看:
OfflineDoc: Offline documents generating tool
Usage: od.py <action> [arg] ...
od.py new <dir> - create a project and place data into <dir>
od.py update <dir> [module [version]] - update a project in <dir> (optional specific module, version)
od.py index <dir> - rebuild index html files in <dir>
od.py serve <dir> - simple http server for <dir> (alias python -m SimpleHTTPServer)
od.py clear <dir> - clear all data in <dir> (alias rm -rf <dir>)
od.py list [dir] - list all modules (optional with custom modules in a dir)
od.py auth <dir> - setup github auth for a project
od.py version - current version
od.py help - prints this info
Turn on debug mode:
ODDEBUG=1 od.py <action> [arg] ...
普遍使用流程是这样:
-
选择一个大分区目录用来存放离线文档,比如
/var/data/od
,则使用od.py new /var/data/od
初始化之:$od.py new /var/data/od Project created, here's an example nginx config: server { listen 80; server_name localhost.doc; access_log off; error_log /dev/null; root /var/data/od/public; location = /index.html { expires epoch; } location ~ ^/[^\/]+/index.html$ { expires epoch; } }
会显示一个 nginx 配置示例,把这块加入 nginx 配置后,就可以网页浏览生成好的离线文档了。当然需要安装 nginx,不过 OfflineDoc 也有自带一个小 http 服务器供文档浏览。
-
github 认证:
od.py auth /var/data/od
。由于部分内置项目托管在 github 上,OfflineDoc 有用到 github 的 api 接口,所以需要在该数据目录中保存一个 github 账号信息。可以花一两分钟去创建一个 github 账号。 -
开始更新:
od.py update /var/data/od
。这会把内置的二十多个项目的几乎所有版本的离线文档都生成出来,当然是比较花时间的。可以选择性生成。比如od.py update /var/data/od bootstrap
会只生成 bootstrap 所有版本的文档,执行od.py update /var/data/od bootstrap 2.3.2
只会生成 bootstrap 2.3.2 版本的文档。 -
生成索引:
od.py index /var/data/od
。这步不是必须的。当你单独更新了某个项目的文档时,浏览器里没有看到变化,可以执行此命令重新生成所有项目的索引页面。 -
浏览文档:
od.py serve /var/data/od
。这会在本机 8000 端口启动一个 http 服务,访问即可看到生成好的文档。 -
查看目前已有项目列表及最新版本:
od.py list /var/data/od
不加最后一个参数会只显示内置项目列表,加上会显示在那个数据目录中的版本号,而且该数据目录中的自定义项目。
如果遇到问题,可以把 ODDEBUG=1
加在 od.py
命令前面,例如:ODDEBUG=1 od.py update /var/data/od
,这样会输出调试信息,方便排查。错误信息可以贴到 https://github.com/ichuan/OfflineDoc/issues 。
可以把更新命令放入 crontab,每日更新,这样就能时刻保持文档最新。
这里有个更新完毕后的站点供参考:http://doc.ichuan.net/
除了这些,OfflineDoc 还支持自定义项目和索引页面主题自定义。
关于自定义项目,可以参考生成的数据目录 /var/data/od 中的 module 目录,其中有四个示例,分别对应 git、svn、单 html 页面个需要 wget 镜像的项目。自定义模块的文件名以下划线开头的话是会被 OfflineDoc 忽略的。
关于自定义主题,可以参考 OfflineDoc 源码,同样在数据目录下的 theme 目录中添加自己的 jinja2 模板文件,OfflineDoc 生成索引时会优先使用此目录的模板文件,而非系统内置。
目前有下面几块需要帮忙完善:
- 除了现在内置的二十多个,继续补充常用的文档
- 其它主题模板(例如 bootstrap 风格等)
- 使用,指出遇到的 bug
- 扩展开发文档
- 单元测试
- 各项目(module)独立的环境(virtualenv, nvm, rvm)