Dash是mac上的一款查看API的工具,里面能够直接下载大部分的API文档,可是有时候我们假设想把自己手里已有的文档也集成到Dash中,就须要我们自己动手了,事实上Dash官方也有教程怎样制作docSet的,地址是:http://kapeli.com/docsets (7. Any HTML Documentation)
, 本文是我照着官方的教程,把流程步骤一步一步的记录下来的,大家能够參考一下。
Dash所需的文档都是docSet文件,事实上docSet文件就是一个目录而已,这个目录里面放了终于的html文档,以及依据这些html建好的索引(索引是放在sqlite数据库中),非常easy。
下文我以mysql5.1官方的中文文档(html)为例,来说明怎样依据html文档一步步创建docSet
1. 从mysql的官网上下载5.1的html中文文档,下载地址为: http://downloads.mysql.com/docs/refman-5.1-zh.html-chapter.zip , 下载后解压缩,会发现里面全都是一些html文件,当中有2个须要关注,一个index.html,一个是ix01.html,第一个是首页的文件夹,第二个是全部的索引列表,这2个文件中基本上包含了全部的mysql索引,我们后面就要把这2个文件中的内容按dash要求的格式来建立索引。
2. 建立文件夹。本例中我们创建的文档就叫mysql51吧,所以按下列结构创建文件夹:
mkdir -p mysql51.docset/Contents/Resources/Documents/
3. 把全部的html文档复制到Documents目录中。
4. 在mysql51.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>dashIndexFilePath</key>
<string>index.html</string>
<key>CFBundleIdentifier</key>
<string>mysql51</string>
<key>CFBundleName</key>
<string>mysql51</string>
<key>DocSetPlatformFamily</key>
<string>mysql51</string>
<key>isDashDocset</key>
<true/>
</dict>
</plist>
能够看到这个文件就是一个xml文件,里面都是一对一对的key-string配置项,当中:dashIndexFilePath这个key相应的string是index.html,表示在Dash中点击你的文档后,默认的主页是什么,其它的key表示你创建的文档名字和keyword之类的,我这里都写成了mysql51.
5. 创建sqlite索引。索引文件的位置是:mysql51.docset/Contents/Resources/docSet.dsidx
,Mac电脑已经预装了sqlite,所以直接从命令行进入Resources目录,在命令行中敲:
sqlite3 docSet.dsidx
这样就进入了sqlite数据库,接下来,创建数据表:
CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
完毕以后敲:.exit 就能够退出sqlite了,这时候你会看到在Resources文件夹下已经有了一个docSet.dsidx文件,兴许我们的索引都会放到刚才创建的searchIndex表中。(在sqlite中输入".exit"就能够退出了,其它命令能够输入".help"查看)
官方教程中事实上在创建表以后还创建了一个unique index,我们这里不能这么搞,后面会讲到,我们的文档一个key有多个索引,所以不能是unique。
6. 接下来就是往searchIndex表中插数据了,SQL模板是:
INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('name', 'type', 'path');
当中name就是我们的keyword,比方你想在dash中输入一个select就能够查询,那这个select就是keyword;type是keyword的类型,官方支持的有非常多,什么Class,Function,Keyword等,我这里偷了个懒,所实用Keyword了;path就是我们的详细文件名了,能够是带锚点的形式,如:client-side-scripts.html#mysqladmin。
7. 把全部的索引数据都插入到searchIndex以后,docSet文档就制作好了,直接双击mysql51.docSet就能够导入Dash了。
以下说说怎么通过html文件制作索引并插入到sqlite数据库,Dash的官方教程中提供了非常多脚本,有python,ruby,php,oc,nodejs等,事实上你用什么语言都能够,仅仅要能生成一份sql文件,在sqlite中通过.read 命令导入即可。 让我们用php来尝试一次吧,由于mysql有2个索引文件,一个index.html,一个是ix01.html,我写了2个php的脚本,就是输出一大堆sql:
<?php header('Content-type: text/html; charset=utf-8');
echo "<meta charset='utf-8'/>";
$dom = new DomDocument;
@$dom->loadHTMLFile("/Users/xxx/Desktop/docSet/mysql51.docset/Contents/Resources/Documents/index.html"); foreach ($dom->getElementsByTagName("a") as $a) {
$href = $a->getAttribute("href");
if (substr($href, 0, 1) == ".") continue;
if (substr($href, 0, 5) == "http:") continue; $name = trim($a->nodeValue);
$name = trim(preg_replace("#\s+#", "", preg_replace("#^([A-Z0-9–]+\.)+#", "", $name)));
if (empty($name)) continue;
$class = "Keyword";
$links[$name] = true;
echo "INSERT INTO searchIndex(name, type, path) VALUES ('". $name . "','". $class ."','". $href ."');<br/>";
}
?>
<?php header('Content-type: text/html; charset=utf-8');
echo "<meta charset='utf-8'/>";
$dom = new DomDocument;
@$dom->loadHTMLFile("/Users/bokix/Desktop/docSet/mysql51.docset/Contents/Resources/Documents/ix01.html"); foreach ($dom->getElementsByTagName("dt") as $a) {
$name = $a->nodeValue;
//echo "$name";
//echo "<br/>";
//echo "===================$name <br/>";
$children = $a->childNodes;
if($children->length == 1){
//echo $name . "has no child <br/>";
continue;
}
for($i = 0; $i < $children->length; $i++)
{
$child = $children->item($i);
if($i==0){
$name = trim($child->nodeValue);
if(substr($name,-3) == ","){
$name = substr($name,0,$name->length-3);
}
//$name = mysql_real_escape_string($name);
}
if($child->nodeName !="a"){
//echo "[".$child->nodeValue . "]not a anchor <br/>";
continue;
} $href = $child->getAttribute("href");
$hrefName=trim($child->nodeValue);
$class = "Keyword"; //$hrefName = mysql_real_escape_string($hrefName); echo "INSERT INTO searchIndex(name, type, path) VALUES ('". $name . "','". $class ."','". $href ."');<br/>";
echo "INSERT INTO searchIndex(name, type, path) VALUES ('". $hrefName . "','". $class ."','". $href ."');<br/>"; } } ?>
执行以后屏幕上会输出一堆堆sql语句,分别保存到2个文件中,比方说1.sql和2.sql,这里须要注意下,sqlite对于单引號的转义是在单引號前面再加一个单引號,和其它sql不同,而我们的索引html里面,有些name本身就是带有"\'"(斜杠加单引號)的,所以你要手工改一下,还好就2个地方,在sql文件中搜索:\' , 在单引號前再加一个单引號。
sql文件生成以后,把2个sql文件复制到docSet.dsidx的文件夹,開始导入sqlite吧:
sqlite3 docSet.dsidx
.read 1.sql
.read 2.sql
假设sql正确运行,屏幕上不会输出什么,假设输出一大堆sql语句,那说明sql有问题,翻到第一条,看看什么错误,然后改动下又一次导入,假设你怕导反复了,也能够把searchIndex表清空然后又一次导入。
这是我生成的几个sql样例:
INSERT INTO searchIndex(name, type, path) VALUES ('OCT()','Keyword','functions.html#string-functions');
INSERT INTO searchIndex(name, type, path) VALUES ('字符串函数','Keyword','functions.html#string-functions');
INSERT INTO searchIndex(name, type, path) VALUES ('OCTET_LENGTH()','Keyword','functions.html#string-functions');
INSERT INTO searchIndex(name, type, path) VALUES ('字符串函数','Keyword','functions.html#string-functions');
INSERT INTO searchIndex(name, type, path) VALUES ('ODBC','Keyword','connectors.html#odbc-connector');
INSERT INTO searchIndex(name, type, path) VALUES ('MySQL Connector/ODBC','Keyword','connectors.html#odbc-connector');
INSERT INTO searchIndex(name, type, path) VALUES ('partitioning types','Keyword','partitioning.html#partitioning-types');
INSERT INTO searchIndex(name, type, path) VALUES ('分区类型','Keyword','partitioning.html#partitioning-types');