Dash文檔製做教程

前言

什麼是Dash

• 面向程序員的文檔庫（Mac）
• 代碼片斷管理工具

這是強烈推薦給天天在各類API文檔中摸爬滾打的程序員們的神器。

爲何要本身製做文檔

• 官方的源中沒有相關文檔
• 文檔在離線下體驗更好

最近在研究 Phantomjs ，相關的文檔比較缺少，主要是看官網的教程及API等，遇到一個問題就是家裏的網絡訪問國外的站點太慢，體驗太差。多是由於技術較新的緣由，發現Dash中並無相關文檔，給Dash做者反饋後，獲得了以下的答覆：

I've recorded your vote towards a PhantomJS docset. Currently, this docset has 11 votes. Please note that I don't generate docsets unless more users ask for them.


You can, however, generate your own docsets by following the instructions at http://kapeli.com/docsets.

呵呵，看來只有本身動手，豐衣足食了。

---

製做教程

前提

1. Mac系統；須要安裝 python 環境，第三方庫 bs4
2. 原始的文檔在網站上（官網上所謂的 7. Any HTML Documentation），例如本例 http://phantomjs.org/

生成站點鏡像

cd ~ && wget -m http://phantomjs.org/

本例中使用 wget 的 --mirror(-m) 選項創建一個鏡像站點，會把站點的各層目錄、文件（圖片、樣式、html等）保存到本地，這些文件就是要導入到Dash的最原始的文件。

文本處理

通過上一步創建到本地的鏡像文件裏面極可能使用的是絕對路徑（例如<a href="http://phantomjs.org/release-names.html"），想要離線索引，就必須先轉換成相對路徑（注意不一樣的層級關係），建議先進行簡單的分析，而後用腳本進行批處理。

這一步是比較重要的一步，會影響到文檔的質量，若是處理很差極可能某些連接因爲路徑不對而看不了。

例如我根據不一樣的目錄層級關係，對html裏面的域名進行不一樣層級的替換：

for dir in `ls -d ~/phantomjs.org/api/*/`; do 
    sed -i 's/http:..phantomjs.org/..\/..\//g' $dir/*.html;
    for sub in `ls -d $dir*/`; do
        sed -i 's/http:..phantomjs.org/..\/..\/..\//g'  $sub*.html;
    done
done

拷貝文檔

Dash要求相求文檔文件要放在 *.docset 目錄下，能夠按照默認的目錄層級：

mkdir -p Phantomjs.docset/Contents/Resources/Documents/
mv ~/phantomjs.org/* Phantomjs.docset/Contents/Resources/Documents/

建立Info.plist文件

裏面能夠定義一些配置信息，例如是否容許Js等

touch Phantomjs.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>CFBundleIdentifier</key>
    <string>Phantomjs</string>
    <key>CFBundleName</key>
    <string>Phantomjs</string>
    <key>DocSetPlatformFamily</key>
    <string>Phantomjs</string>
    <key>isDashDocset</key>
    <true/>
</dict>
</plist>

生成索引

• 先建立一個SQLite數據庫文件，並生成一張表。

sqlite3 Phantomjs.docset/Contents/Resources/docSet.dsidx
CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
.exit

• 用 python 腳本填充索引

這一步也是比較重要的一步，也是最複雜的一步。數據庫文件的索引對應Dash文檔的目錄（或者索引），質量高的索引能夠表達出很豐富層級關係以及分類，例如函數、類、熟悉、模塊、分類、條目、命令等。

簡單起見，這裏只填充了官網首頁的4個‘分類’（Category），使用 python 實現，具體如何填充須要根據文檔實際狀況調整腳本：

#!/usr/local/bin/python

import os, re, sqlite3
from bs4 import BeautifulSoup, NavigableString, Tag

db = sqlite3.connect('Phantomjs.docset/Contents/Resources/docSet.dsidx')
cur = db.cursor()

try: 
    cur.execute('DROP TABLE searchIndex;')
except: 
    pass

cur.execute('CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);')
cur.execute('CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);')

docpath = 'Phantomjs.docset/Contents/Resources/Documents'

page = open(os.path.join(docpath,'index.html')).read()
soup = BeautifulSoup(page)

any = re.compile('^[a-z]{3,20}$|documentation.html|faq.html')
for tag in soup.find_all('a', {'href':any}):
    name = tag.text.strip()
    if len(name) > 0:
        path = tag.attrs['href'].strip()
        if path.split('#')[0] not in ('index.html', 'index.htm', 'bookindex.html'):
            cur.execute('INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES (?,?,?)', (name, 'Category', path))
            print 'name: %s, path: %s' % (name, path)

db.commit()
db.close()

添加icon及其餘註釋說明等

製做一個 logo 後（從官網logo截一張大圖），導出兩種尺寸，16x1六、 32x32

touch Phantomjs.docset/icon.png
touch Phantomjs.docset/icon@2x.png

此時，雙擊Phantomjs.docset便可導入到 Dash 中了，還能夠在偏好設置裏面刷新文檔內容，若是有修改 logo 須要先刪除文檔再添加進來。

---

共享到社區（github）

經過互聯網貢獻一點本身的努力吧。

• fork 項目 https://github.com/Kapeli/Dash-User-Contributions
• 按照裏面的要求把本身的文件上傳上去，而後就能夠 pull request 了

---

參考

該文只是記錄了本身在製做文檔過程當中的基本思路，請你們必定仔細參考官網的教程：

• Generating Dash Docsets
• Kapeli/Dash-User-Contributions