Dash文档制作教程

前言

什么是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.

呵呵，看来只有自己动手，丰衣足食了。

---

制作教程

前提

1. Mac系统；需要安装 python 环境，第三方库 bs4
   
2. 原始的文档在网站上（官网上所谓的 7. Any HTML Documentation），例如本例 http://phantomjs.org/

生成站点镜像

cd ~ && wget -m http://phantomjs.org/

本例中使用 wget 的 --mirror(-m) 选项建立一个镜像站点，会把站点的各层目录、文件（图片、样式、html等）保存到本地，这些文件就是要导入到Dash的最原始的文件。

文本处理

经过上一步建立到本地的镜像文件里面很可能使用的是绝对路径（例如<a href="http://phantomjs.org/release-names.html"），想要离线索引，就必须先转换成相对路径（注意不同的层级关系），建议先进行简单的分析，然后用脚本进行批处理。

这一步是比较重要的一步，会影响到文档的质量，如果处理不好很可能某些链接由于路径不对而看不了。

例如我根据不同的目录层级关系，对html里面的域名进行不同层级的替换：

for dir in `ls -d ~/phantomjs.org/api/*/`; do 
	sed -i 's/http:..phantomjs.org/..\/..\//g' $dir/*.html;
  	for sub in `ls -d $dir*/`; do
		sed -i 's/http:..phantomjs.org/..\/..\/..\//g'  $sub*.html;
  	done
done

拷贝文档

Dash要求相求文档文件要放在 *.docset 目录下，可以按照默认的目录层级：

mkdir -p Phantomjs.docset/Contents/Resources/Documents/
mv ~/phantomjs.org/* Phantomjs.docset/Contents/Resources/Documents/

创建Info.plist文件

里面可以定义一些配置信息，例如是否允许Js等

touch Phantomjs.docset/Contents/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>Phantomjs</string>
    <key>CFBundleName</key>
    <string>Phantomjs</string>
    <key>DocSetPlatformFamily</key>
    <string>Phantomjs</string>
    <key>isDashDocset</key>
    <true/>
</dict>
</plist>

生成索引

• 先创建一个SQLite数据库文件，并生成一张表。

sqlite3 Phantomjs.docset/Contents/Resources/docSet.dsidx
CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
.exit

• 用 python 脚本填充索引

这一步也是比较重要的一步，也是最复杂的一步。数据库文件的索引对应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 = db.cursor()

try: 
	cur.execute('DROP TABLE searchIndex;')
except: 
	pass

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);')

docpath = 'Phantomjs.docset/Contents/Resources/Documents'

page = open(os.path.join(docpath,'index.html')).read()
soup = BeautifulSoup(page)

any = re.compile('^[a-z]{3,20}$|documentation.html|faq.html')
for tag in soup.find_all('a', {'href':any}):
    name = tag.text.strip()
    if len(name) > 0:
        path = tag.attrs['href'].strip()
        if path.split('#')[0] not in ('index.html', 'index.htm', 'bookindex.html'):
            cur.execute('INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES (?,?,?)', (name, 'Category', path))
            print 'name: %s, path: %s' % (name, path)

db.commit()
db.close()

添加icon及其他注释说明等

制作一个 logo 后（从官网logo截一张大图），导出两种尺寸，16x16、 32x32

touch Phantomjs.docset/icon.png
touch Phantomjs.docset/[email protected]

此时，双击Phantomjs.docset即可导入到 Dash 中了，还可以在偏好设置里面刷新文档内容，如果有修改 logo 需要先删除文档再添加进来。

---

共享到社区（github）

通过互联网贡献一点自己的努力吧。

• fork 项目 https://github.com/Kapeli/Dash-User-Contributions
  
• 按照里面的要求把自己的文件上传上去，然后就可以 pull request 了

---

参考

该文只是记录了自己在制作文档过程中的基本思路，请大家一定仔细参考官网的教程：

• Generating Dash Docsets
  
• Kapeli/Dash-User-Contributions