Dash助手: 任意html转换为Docset

原文地址

做为一名程序员，最离不开的就是文档了，大多数状况下咱们都是经过文档了解一个陌生的领域。想象一下，打开了一堆文档，在文档中跳来跳去，多么的不优雅！因此Bogdan Popescu一怒之下开发了dash，解放了太多在文档中跳来跳去的码农。

dash主要有如下特色：

• 自带大量经常使用文档(iOS/Mac/PHP/Python/Java等)

• 支持用户自定义文档(scrapy/requests/beautifulsoup等)

• 快速搜索文档及 API

• 管理和搜索代码片断

• 无缝插入众多第三方应用(Alfred/Xcode/Terminal等)

dash界面左侧列出全部的文档，支持标签页和书签功能，在搜索框内经过输入关键字，能够查找相关的API、文档，而且响应速度很是快！下面先来一睹Dash芳容吧：

虽然说dash官方给了足够多的Docset文档，不过有时候仍然不够用，这时候咱们能够去找第三方的Docset，若是找不到，那么只好本身动手丰衣足食啦。

其生成DocSets帮助文档中，有许多种生成Docset的方法介绍，好比从AppleDoc(Objective-C Source Files)、Python(Sphinx or PyDoctor)
、Javadoc、Any HTML Documentation生成文档等。注意，这里能够从Any HTML Documentation生成Docset文档，真是大福利！

html2Dash

相信你们都很喜欢python的requests吧，它的语法以及文档十分简单明了，不愧它HTTP for Humans的称号。在使用Dash以前，我将requests的文档镜像到本地，以便随时使用。其实，我不仅离线了requests的文档，还有beautifulsoup四、scrapy等许多文档。我甚至将酷壳整个站点都离线了下来，以便拜读人家的文章。

当我碰见Dash以后，我经常想若是能将我离线的文档转换为Docset格式，丢给Dash管理，那该多美妙。幸亏，dash官网提供了html文件转换为DocSet的方法，整个转换主要有如下几个步骤：

1. 建立Docset目录结构(Create the Docset Folder)；

2. 复制HTML文件(Copy the HTML Documentation)；

3. 建立Info.plist文件(Create the Info.plist File)；

4. 建立SQLite数据库文件(Create the SQLite Index)；

5. 写入SQLite数据索引(Populate the SQLite Index)；

为了将转换的过程自动化，我写了一个小程序html2dashhtml2dash放在github上，使用十分简单，能够用./html2dash.py -h查看帮助，以下：

$ /html2dash.py -h
usage: html2dash.py [-h] [-n NAME] [-d PATH] [-i FILENAME] [-p INDEX_PAGE]
                    SOURCE

positional arguments:
  SOURCE                Directory containing the HTML documents

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name the docset explicitly
  -d PATH, --destination PATH
                        Put the resulting docset into PATH
  -i FILENAME, --icon FILENAME
                        Add PNG icon FILENAME to docset
  -p INDEX_PAGE, --index-page INDEX_PAGE
                        Set the file that is shown

下面是转换requests文档的示例：

$ ./html2dash.py -n requests -i ~/Documents/requests-sidebar.png ~/Documents/requests  
Create the Docset Folder!  
Copy the HTML Documentation!  
Create the SQLite Index    
Create the Info.plist File  
Create the Icon for the Docset!  
Generate Docset Successfully!

效果以下：

从HTML制做的文档其实不算真正意义上的“文档”，由于并无Classes、Functions、Types等API，以下图：

下面介绍一下我经常使用的镜像站点的方法。

镜像站点

镜像站点最简单的方法就是使用wget，通常像这样使用：

wget -r -p -k -np http://tengine.taobao.org/book/

关于wget的更多内容，能够看以前的一篇文章：如何使用wget

其实OS X 下有一款比较不错的工具能够用来镜像站点，那就是SiteSucker。好比要下载requests的文档，只须要输入文档首页地址，而后设置Path Constraint为Directory便可下载文档，以下图：

前面两种镜像方法都不是很完美，由于有时候某些站点(好比Scrapy)引用的css、js文件来自其余的站点，这时候若是选择只镜像当前目录下面的文件，就会漏掉这些资源文件，目前尚未找到一个合适的方法解决这个问题。

参考：
Dash-Docset-Creator
Generate a docset from any HTML Documentation