在Mac电脑上为Dash制作docSet文档

原创 2014年07月19日 10:32:47

Dash是mac上的一款查看API的工具,里面可以直接下载大部分的API文档,但是有时候我们如果想把自己手里已有的文档也集成到Dash中,就需要我们自己动手了,其实Dash官方也有教程如何制作docSet的,地址是:http://kapeli.com/docsets  (7. Any HTML Documentation) , 本文是我照着官方的教程,把流程步骤一步一步的记录下来的,大家可以参考一下。


Dash所需的文档都是docSet文件,其实docSet文件就是一个文件夹而已,这个文件夹里面放了最终的html文档,以及根据这些html建好的索引(索引是放在sqlite数据库中),很简单。


下文我以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表示你创建的文档名字和关键字之类的,我这里都写成了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就是我们的关键字,比如你想在dash中输入一个select就可以查询,那这个select就是关键字;type是关键字的类型,官方支持的有很多,什么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');







Dash助手- 任意html转换为Docset

原文地址 作为一名程序员,最离不开的就是文档了,大多数情况下我们都是通过文档了解一个陌生的领域。想象一下,打开了一堆文档,在文档中跳来跳去,多么的不优雅!所以Bogdan Popescu一怒之下开发...
  • cangdu
  • cangdu
  • 2015年01月05日 02:33
  • 834

javase各版本官方文档

javase1.4.2官方在线文档(官方已经不提供在线文档了,有兴趣的可以通过以下地址下载) http://docs.oracle.com/javase/1.4.2/docs/api/index.ht...
  • zhengweijava
  • zhengweijava
  • 2014年01月13日 19:37
  • 659

Dash前端工程师的好帮手

作为一名死coder,每天最常见的动作就是查看各种API文档,你一定也有过同时打开N个窗口(HTML、PDF、CHM),不停的在编辑器与文档之间切换的感受吧?怎么说呢,其实我很讨厌这种枯燥无味的动作,...
  • jasonzds
  • jasonzds
  • 2016年10月30日 20:18
  • 410

Dash助手- 任意html转换为Docset

原文地址 作为一名程序员,最离不开的就是文档了,大多数情况下我们都是通过文档了解一个陌生的领域。想象一下,打开了一堆文档,在文档中跳来跳去,多么的不优雅!所以Bogdan Popescu一怒之下开发...
  • cangdu
  • cangdu
  • 2015年01月05日 02:33
  • 834

Dash 安装 IOS文档 Apple 开发者离线文档下载

Why 苹果官网的IOS Developer Library是开发者最喜欢用的知识仓库,但由于有时打开它实在太慢了 How 下载方法 打开这个官网提供的连接点击打开链接   这个链接返回的是...
  • shan1991fei
  • shan1991fei
  • 2016年02月25日 23:50
  • 1445

Xcode下为 IOS 制作 framework

写在前面: 通过 Framework 可以在物理上实现 iOS 程序的模块化。 好处:       1、如果模块间接口定义的比较完善,模块化的程序具有很好的可扩展性与内聚性;       2、...
  • muyu114
  • muyu114
  • 2013年07月23日 16:09
  • 1050

在Mac电脑上为Dash制作docSet文档

Dash是mac上的一款查看API的工具,里面可以直接下载大部分的API文档,但是有时候我们如果想把自己手里已有的文档也集成到Dash中,就需要我们自己动手了,其实Dash官方也有教程如何制作docS...
  • langhong8
  • langhong8
  • 2015年06月19日 11:24
  • 395

添加Xcode自定义docset文档

一、生成docset文档1.安装appledoc appledoc是一个文档生成工具,只为Objective-C服务(很专一),能生成和Apple一个风格的文档,可以直接编译成docset安装进xco...
  • LCZJYCoder
  • LCZJYCoder
  • 2017年04月06日 14:46
  • 323
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:在Mac电脑上为Dash制作docSet文档
举报原因:
原因补充:

(最多只允许输入30个字)