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

原文地址

作為一名程序員，最離不開的就是文檔了，大多數(shù)情況下我們都是通過文檔了解一個陌生的領(lǐng)域。想象一下，打開了一堆文檔，在文檔中跳來跳去，多么的不優(yōu)雅！所以Bogdan Popescu一怒之下開發(fā)了dash，解放了太多在文檔中跳來跳去的碼農(nóng)。

dash主要有以下特點(diǎn)：

自帶大量常用文檔(iOS/Mac/PHP/Python/Java等)

支持用戶自定義文檔(scrapy/requests/beautifulsoup等)

快速搜索文檔及 API

管理和搜索代碼片段

無縫插入眾多第三方應(yīng)用(Alfred/Xcode/Terminal等)

dash界面左側(cè)列出所有的文檔，支持標(biāo)簽頁和書簽功能，在搜索框內(nèi)通過輸入關(guān)鍵字，可以查找相關(guān)的API、文檔，并且響應(yīng)速度非常快！下面先來一睹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的文檔鏡像到本地，以便隨時使用。其實(shí)，我不只離線了requests的文檔，還有beautifulsoup4、scrapy等許多文檔。我甚至將酷殼整個站點(diǎn)都離線了下來，以便拜讀人家的文章。

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

創(chuàng)建Docset目錄結(jié)構(gòu)(Create the Docset Folder)；

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

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

創(chuàng)建SQLite數(shù)據(jù)庫文件(Create the SQLite Index)；

寫入SQLite數(shù)據(jù)索引(Populate the SQLite Index)；

為了將轉(zhuǎn)換的過程自動化，我寫了一個小程序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

下面是轉(zhuǎn)換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制作的文檔其實(shí)不算真正意義上的“文檔”，因?yàn)椴]有Classes、Functions、Types等API，如下圖：

下面介紹一下我常用的鏡像站點(diǎn)的方法。

鏡像站點(diǎn)最簡單的方法就是使用wget，一般像這樣使用：

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

關(guān)于wget的更多內(nèi)容，可以看之前的一篇文章：如何使用wget

其實(shí)OS X 下有一款比較不錯的工具可以用來鏡像站點(diǎn)，那就是SiteSucker。比如要下載requests的文檔，只需要輸入文檔首頁地址，然后設(shè)置Path Constraint為Directory即可下載文檔，如下圖：

前面兩種鏡像方法都不是很完美，因?yàn)橛袝r候某些站點(diǎn)(比如Scrapy)引用的css、js文件來自其他的站點(diǎn)，這時候如果選擇只鏡像當(dāng)前目錄下面的文件，就會漏掉這些資源文件，目前還沒有找到一個合適的方法解決這個問題。

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