Dash/Zealで使えるmruby APIのDocsetを作った

mruby APIのオンラインドキュメントをDocset化した。 DocsetはDashやZealで閲覧できる。オフラインでmrubyのAPIを参照できるので便利。

なお、私はMacを持っていないのでDashでの動作確認はしていないのであしからず…。 ↓のFeed URLから追加できるはず(Zealでは確認した)。 https://raw.githubusercontent.com/buty4649/mruby-api-docset/main/mruby-3.2.0-api.xml Dash向けはこちら *1。

github.com

Docsetの作り方

Docsetの作り方は公式のページに書いてある。

kapeli.com

簡単に書くと、以下のようなディレクトリ構成とファイルを作成してtarballにすればよい。ディレクトリ構成はこんな感じ。

(Docsetの名前).docset
└── Contents
    ├── Info.plist
    └── Resources
        ├── docSet.dsidx
        └── Documents
                 └── (以下、ドキュメントファイル)

Info.pistはXMLになっており、以下のような内容を記述すればよい。なお、各パラメータがどういう意味なのかは正しく理解していない。

<?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>(Docsetの名前)</string>
    <key>CFBundleName</key>
    <string>(Docsetの名前)</string>
    <key>DocSetPlatformFamily</key>
    <string>(Docsetの名前？)</string>
    <key>isDashDocset</key>
    <true/>
    <key>dashIndexFilePath</key>
    <string>(Docsetを開いたときに表示するページ)</string>
  </dict>
</plist>

docSet.dsidxはsqlite3のDBファイルになっている。このDBファイルにsearchIndexテーブルを作り、そこにDocsetに含まれる項目を登録していく。 searchIndexは公式ドキュメントにある通り、以下のSQLで作成できる。

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

項目の追加は以下のようなSQLで行う。

INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('name', 'type', 'path');

name には項目の名前を入れる
type は項目の種類を指定する
- 指定できる種類は公式ドキュメントを参照のこと -> 13.5.1. Supported Entry Types
path にはドキュメントのパスをDocumentsディレクトリをrootとしたときの相対パスを入れる

最後にtarballを作成する

tar --exclude='.DS_Store' -cvzf <Docsetの名前>.tgz <Docsetの名前>.docset

このtarballをDash/ZealのDocsetディレクトリに解凍すれば見られるようになる。 tarballをオンラインで配布する場合、HTTPでアクセスできるオンラインストレージにtarballを配置し、以下のFeedファイルも一緒に配置する。

<entry>
  <version>(Docsetのバージョン)</version>
  <url>(DocsetのtarballのURL)</url>
</entry>

このFeedのURLをZealに登録すればダウンロードされる。 Dashの場合、 dash-feed://<URL encoded feed URL> というURLリンクを作ればリンクをクリックするだけでダウンロードされる(未確認)。

おわりに

DashであればRDoc、YardをDocsetとして扱えるっぽい？のだがZealはできなかったのでそれであればとDocsetを作成した。公式ドキュメントも用意されていて、いくつかサンプルもありそんなに難しくなくDocsetが作れてよかった。

しかしながら、Dashはあまり活発に開発されていないっぽいし、Zealも開発停止はしていないようだがあまり活発ではなさそうなのが少し心配。今どきのオフラインドキュメントビューワーはみんなどうしているんだろうか、気になっている。

*1:GitHubのMarkdownだとdash-feedスキーマはリンクにできなかった。セキュリティ的な懸念があるからだろうか？

ぶていのログでぶログ

思い出したが吉日

Dash/Zealで使えるmruby APIのDocsetを作った

Docsetの作り方

おわりに