摘要：在使用之前，我將的文檔鏡像到本地，以便隨時使用。當我遇見之后，我常常想如果能將我離線的文檔轉換為格式，丟給管理，那該多美妙。

原文地址

作為一名程序員，最離不開的就是文檔了，大多數情況下我們都是通過文檔了解一個陌生的領域。想象一下，打開了一堆文檔，在文檔中跳來跳去，多么的不優雅！所以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文檔，真是大福利！

相信大家都很喜歡python的requests吧，它的語法以及文檔十分簡單明了，不愧它HTTP for Humans的稱號。在使用Dash之前，我將requests的文檔鏡像到本地，以便隨時使用。其實，我不只離線了requests的文檔，還有beautifulsoup4、scrapy等許多文檔。我甚至將酷殼整個站點都離線了下來，以便拜讀人家的文章。

當我遇見Dash之后，我常常想如果能將我離線的文檔轉換為Docset格式，丟給Dash管理，那該多美妙。幸好，dash官網提供了html文件轉換為DocSet的方法，整個轉換主要有以下幾個步驟：

創建Docset目錄結構(Create the Docset Folder)；

復制HTML文件(Copy the HTML Documentation)；

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

創建SQLite數據庫文件(Create the SQLite Index)；

寫入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