前言
什么是Dash
面向程序员的文档库(Mac)
代码片段管理工具
这是强烈推荐给每天在各种API文档中摸爬滚打的程序员们的神器。
为什么要自己制作文档
官方的源中没有相关文档
文档在离线下体验更好
最近在研究 Phantomjs ,相关的文档比较缺乏,主要是看官网的教程及API等,遇到一个问题就是家里的网络访问国外的站点太慢,体验太差。可能是因为技术较新的原因,发现Dash中并没有相关文档,给Dash作者反馈后,得到了如下的答复:
I've recorded your vote towards a PhantomJS docset. Currently, this docset has 11 votes. Please note that I don't generate docsets unless more users ask for them.
You can, however, generate your own docsets by following the instructions at http://kapeli.com/docsets.
呵呵,看来只有自己动手,丰衣足食了。
制作教程
前提
Mac系统;需要安装 python 环境,第三方库 bs4
原始的文档在网站上(官网上所谓的 7. Any HTML Documentation),例如本例http://phantomjs.org/
生成站点镜像
cd ~ && wget -m http://phantomjs.org/
本例中使用 wget 的 --mirror(-m) 选项建立一个镜像站点,会把站点的各层目录、文件(图片、样式、html等)保存到本地,这些文件就是要导入到Dash的最原始的文件。
文本处理
经过上一步建立到本地的镜像文件里面很可能使用的是绝对路径(例如
这一步是比较重要的一步,会影响到文档的质量,如果处理不好很可能某些链接由于路径不对而看不了。
例如我根据不同的目录层级关系,对html里面的域名进行不同层级的替换:
Dash要求相求文档文件要放在 *.docset 目录下,可以按照默认的目录层级:
touch Phantomjs.docset/Contents/Info.plist
这一步也是比较重要的一步,也是最复杂的一步。数据库文件的索引对应Dash文档的目录(或者索引),质量高的索引可以表达出很丰富层级关系以及分类,例如函数、类、熟悉、模块、分类、条目、命令等。
简单起见,这里只填充了官网首页的4个‘分类’(Category),使用 python 实现,具体如何填充需要根据文档实际情况调整脚本:
#!/usr/local/bin/python import os, re, sqlite3 from bs4 import BeautifulSoup, NavigableString, Tag
db = sqlite3.connect('Phantomjs.docset/Contents/Resources/docSet.dsidx')
cur.execute('DROP TABLE searchIndex;')
cur.execute('CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);')
cur.execute('CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);')
name = tag.text.strip() if len(name) > 0:
print 'name: %s, path: %s' % (name, path)
制作一个 logo 后(从官网logo截一张大图),导出两种尺寸,16x16、 32x32
touch Phantomjs.docset/icon.png touch Phantomjs.docset/icon@2x.png
此时,双击Phantomjs.docset即可导入到 Dash 中了,还可以在偏好设置里面刷新文档内容,如果有修改 logo 需要先删除文档再添加进来。
该文只是记录了自己在制作文档过程中的基本思路,请大家一定仔细参考官网的教程: