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